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Preface 



The purpose of this document is to explain the internal structures and 
algorithms used by the Lisa's run-time environment and development tools^ and 
the internal library units (such as OBJIOLIB) that are related only to Lisa 
systems software. It is actually a collection of documents and memos/ any of 
which can be used separately, all relating to different aspects of the system. 

This is a reference document for programmers working on the following: 

* Maintaining or enhancing existing Lisa development software. 

* Writing compilers or utilities for the Lisa Workshop, either on contract 
with Apple or as third-party independants, 

* Writing assembly-language programs that will interfaced with our compiled 
code. 



How will they benefit from this document? 

* It will save the people maintaining tools the trouble of looking through 
the code themselves to find information. 

♦» It will save outside programmers, who don't have access to the code, from 
calling us to ask questions about things that ve have to look up in the 
code. 

* Parts of it will be included as a reference section in technical 
contracts that we assign to outside programmers. 

* It will provide assembly- language programmers with such specifics as 
register conventions, parameter-passing techniques, and memory layouts 
used by the conmpiler for different types of arrays and structures. 

* It can be used to train new systems software programmers on the existing 
internals of the system. 
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Lisa Development Software 

Documentation: 

A Road Map 



Introduction 



7hh road map was dejigned to help you to find your way around the various 
documents describing program development for the Lisa. It will help you decide 
which software you need to learn more about, which software you can ignore for the 
moment, and how you should proceed in $tudying the rest of the technical 
documentation. 

General (X^erview of the Envtronmenti Mailable 

There are as many ways of writing programs as there are creative programmers. 
However, Apple supports only three general styles of programs that you can write for 
the Liva: those written for 1) the Workshop environment, 2) the QuickPort 
environment, and 3) the ToolKit environment. Programs written for any of these 
environments can use most of the same units and libraries, but there are some 
important differences of which you should be aware. 

The Workshop (Figure 1) provides a simple non-window, character and graphic 
environment within which a program may run. Programs written to run in this 
environment may use Pascal's built-in I/O for both files and textual display to the . 
console's terminal emulatcr, or they may directly utilize the Lisa OS's file system 
primitives. They may also use the QuickDraw unit for drawing bitmap graphics and 
displaying text in a variety of fonts with various attributes, and may utilize a variety 
of other useful library routines. These programs are not able to use the Lisa Desktop 
libraries dealing with windows, menus, and dialog boxes, nor do they have easy access 
to Lisa Office System documents. 

In addition to providing these run-time facilities, the Workshop also Includes a 
command shell which makes available to users an extensive set of facilities for: 1) 
Interactive program development in Pascal, Assembly, BASIC, and COBOL; 2) File and 
device manipulation; and 3) Interactive and batch program execution and control. 

QuickPort (Figure 2) provides the simplest Desktop environment, at least from the 
programmer's viewpoint. In most respects, writing a program for the QuickPort 
environment is identical to s^riting one for the Workshop environment. Using Pascal's 
built-in I A3 facilities, programs written for QuickPort may do textual display to a 
variety of window-based terminal emulators, and may also display graphics using 
QuickDraw. These programs do not directly use the Lisa Desktop libraries, and are, in 
fact, unaware of such things as the window environment, the mouse, and menus. They 
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may, however, exchange information with Lisa Office System documents via the 
Cut/Pa$te mechanism. 

The TooIKit (Figure 3) provides the most complete access to the Desktop facilities 
From the programmer's viewpoint, it also requires the most knowledge of these 
facilities. Programs ssritten using the 'TooIKit use the Generic Application and may 
use any of the TooIKit building blocks, which provide easy, controlled access to the 
Lisa Desktop libraries, the mouse, and menus. They may also ax change information 
with Lisa Office System documents via the Cut/Paste mechanism. 

O/erview cf the Pieces 

QuickPcri is a set of units that are USEd and linked with a program which is to be 
run in the Desktop environment. QuickPort then provides the program with a 
'terminal window", to which the program's console I/O may be directed through the 
use of Pascal's built-in Text I/O facilities. The program simply makes ReadLn and 
WriteLn calls to display text or receive keyboard input. QuickPort code hides from 
the program such issues as cutting and pasting information from other Desktop 
applications, communicating with the Desktop shell, growing and shrinking the window, 
covering arid uncovering the window, and activating or deactivating the prograrri. For 
a program using QuickPort, such issues are of no concern. 

The TooIKit is a set of libraries that provides standard Lisa application behavior, 
including windows that can be moved, resized, and scrolled, pull-down menus with 
standard functions such as saving and printing, and the Cut/Paste mechanism. The 
TooIKit defines the parts of an application common to all Lisa applications. The 
object-oriented structure of the TooIKit allows you to implement your application as 
extensions to the "Generic Application". 

The Lisa Operetiftg System provides the program with an environment in which 
multiple processes can coexist, with the ability to communicate and share data. It 
provides a device-independent file system for I/O and information storage, end handles 
exceptions (software interrupts) and mem.cry management for both £ode and data 
segments. 

PASUB is the Pascal run-time support library. Most of the routines in PASLIB 
support the Pascal built-in facilities, including routines for initialization, integer 
arithmetic, data and string manipulation, sets, range checking, the heap, and I/O. 

Floeiino Pout Liirariet provide numeric routines which implement the proposed IEEE 
Floating Point Standard (Standard 754 for Binary Floating-Point Arithmetic), and 
higher -level mathematical algorithms. FPUb provides Single (32-bit), Double (64-bit), 
and Extended (80-bit) floating-point data types, a 64 -bit Integer data type, conversion 
from one arithmetic type to another (or to ASCII), arithmetic operations, 
transcendental functions, arKi tools for handling exceptions. MeihLib provides, among 
others, algorithms such as extra elementary functions, sorting, extended conversion 
routines, financial analysis, zeros of functions, and linear algebra. 

QuickDraw is a unit for doing bit-mapped graphics. It consists of procedures, 
functions, and data types you need to perform highly complex graphic operations very 
easily and very quickly. You can draw text characters in a number of fonts, with 
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variations that include boldface, italic, underlined, and outlined; you can drew 
aB'titrary or predefined shapes, either hollow or filled; you can drew straight lines of 
any length and width; or you can draw any combination of theje items, with a single 
procedure call. 

The Desktop Ubrahet provide window, yaphics, mouse, and menu routines used by 
all Office System applications. They are not directly called by any programs written 
for the three run-time environment* discussed here, but provide the hidden foundation 
for both the QuickPort arid the ToolKit environments. 

The Harcfwm-e Interface unit lets you access Lisa hardware elements such as the 
mouse/the cursor, the display, the contrast control, the speaker, the keyboard, the 
micro- and millisecond timers, and the hardware clock/calendar. 

The Stendard (MH lets you do string, character, and file-name manipulation, 
prompting, retrieval of messages from disk files, abort exec file processing, and 
conversions between numbers and strings. 

The DPtimttives unit provides you with fast, efficient text-file input and output. 

The Ptogram Communiceiion unit allows programs to communicate with each other 
and with the Workshop shell. 

LiseBug allows you to examine and modify memory, set breakpoints, assemble and 
disassemble instructions, and perform other functions for run-time debugging. 

More Detail 

QuickPort: A program which is to make full use of the capabilities of the Lisa Office 
System will be structured as an endless loop, within which the program continually 
polls the Window Manager for any events it ihould respond to. We will refer to such 
a program as an Inie^&tecf Ffogranrc An integrated program must handle such 
asynchronous events as the program's window being activated or deactivated, the 
window being opened, closed, moved, resized, or needing update, the mouse button 
going down or up, and a key going down or up. The program must also be a good 
citizen in Lisa's multi-tasking but non-preemptive scheduling environment by 
volunteering periodically to yield the CPU to any other process needing service. 
These are just a few of the important characteristics of an integrated program. The 
result of a programi following these and other guidelines will be that it exhibits the 
tame consistent^ responsive behavior as other Apple-written programs like LisaDraw. 

QuickPort li a collection of pieces which make writing programs for the Office 
^$tem*s window environment as easy as writing them for the Workshop's non-window 
environment. NOTE: In order to differentiate the QuickPort modules from the 
program which uses them, we will refer to the program itself as a Vanilla Program. 
QuickPort allows the vanilla program to be more traditionally structured, as if its user 
interfacing were being done through a tmart text/graphics terminal; the vanilla 
program presents its display to the user by a combination of text I/O calls (e.g., 
WriteLn/ReadLn) and QuickDraw calls (e.g., DrawString/PaintRect). The QuickPort 
modules handle all events from the Window Manager, provide for yielding the CPU to 
competing processes at specific points, and in genereJ shelter the program from the 
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sometimej tricky requirements of writing art integrated program for the Lisa Office 
System. 

QuickPort provides the vanilla program with a window, which may be divided into a 
Text Parte! arid a QuickDraw Panel for displaying both textual and yaphic 
information. Each of these optional panels is configurable in size and location, and 
may be independently scrolled horizontally or vertically. Text and Graphics windows 
may be overlaid, $o the resulting window presents a composite of both types of 
output. The window may be resized^ moved, covered, or uncovered without the 
vanilla program even being aware of juch events. Textual and graphic information 
may be exchanged between a vanilla program's document and other documents, 
whether vanilla or integrated, by using the familiar Cut/Paste mechanism. Without 
any effort on the part of the vanilla program, the end user is given a large measure 
of control over the window's configuration and behavior, using mouse and menu 
actions supported by QuickPort. 

The user may request printing of either the text panel or the graphics panel. In 
addition, vanilla progrerris may produce printed output under program control by 
writing to the -PRINTER logical device. Whereas, in the Workshop environment, 
printing is immediate (each line printing as $oon as the program "writes" it), in the 
QuickPort/Desktop environment printing is all spooled. This means that the printed 
output of a vanilla program will be submitted to the Office system's PrintShop, which 
determines from the print queue when the document will be printed. 

The Text Panel emulates a terminal display which corresponds to the Pascal built-in 
OUTPUT file, the built-in INPUT file, and the -CONSOLE and -KEYBOARD logical 
devices. Apple provides emulators for the VTIOO and SOROC terminals, and makes 
It possible for you to either customize them or create entirely new terminal 
emulators. These terminal emulators are actually filters which pre-process the 
character output stream destined for the Standard Terminal Unit,, which provides the 
Text Panel display. Each emulator's job is to recognize the terminal-specific 
character sequences imbedded in the output stream which are commands to the 
terminal, and to call upon the Standard Tcrn^nal Unit to take the appropriate actions. 
A program may eliminate the filtering step, if desired, by calling directly upon the 
Standard Terminal Unit for display actions. 

The Graphics Panel allows your program to display graphics on a bitmap which is a 
maximum of 720 pixels wide by 364 pixels high— the same size as Lisa's physical 
screen bitmap. This panel can be resized by the user or under program control, and 
can be scrolled horizontally and vertically to display different parts of the entire 
bitmap. The Graphics Panel supports every QuickDraw call. Including those related to 
setting foreground and background colors for printed output. An application may 
write anywhere in the coordinate plane of its graphics panel ('grsfPort', to use 
QuickDraw's terminology), without having to worry about where its window is placed 
on the screen or what other windows are in front of it. QuickDraw, with a little help 
from the Window Manager, keeps the application's output from getting out of the 
yaphics panel or from clobbering other windows. 
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The ToolKil: The ToolKit i$ a set of libraries that provides standard behavior that 
follows the design principles characterizing Lisa applications: 

• Extensive use of gj-aphics, including windows and the mouse pointer. 

• Use of pull-down menus for commands. 
■ Few or no operating modes. 

• Data transfer between docunnents by simple cut and paste operations. 

For example, all Lisa applications have windows that can be moved around the screen, 
and that can usually be resized and scrolled. The ToolKit takes care of all these 
functions. The ToolKit also displays a menu bar for the active application, end 
provides a number of staridard menu functions, such as saving, printing, ar»d setting 
aside. 

However, the ToolKit is more than a set of libraries. Because the ToolKit is written 
using Clascal, the ToolKit is almost a complete program by itself. You can, in fact, 
write a five-line main program, compile it, link it with the ToolKit, and run it. Whet 
results is the Generic Application. 

The Generic Application has many of the standard Lisa application characteristics. A 
piece of Generic Application stationary can be torn off, and, when the new document 
is opened, it presents the user with a window with scroll bars, split controls, size 
control, arid a title bar. The mouse pointer is handled correctly when it is over the 
window. The window can be moved, resized, and split into multiple panes. There is a 
menu bar with a few standard functions, so that the generic document can be saved, 
printed, and set aside. The single Generic Application process can manage any 
number of documents. You cannot, however, do anything within the window, aside 
from creating panes. The space within the window, along with the additional menu 
fuctions, is the responsibility of the real application. 

Therefore, when you write a Lisa application using the ToolKit, you essentially write 
extensions to the Generic Application. It is very easy to write extensions to any 
Clascal program. To insert your application's functions, you create a set of 
subclasses, including methods to perform the work of you application, and then you 
write a simple main program, and compile and link it with the ToolKit. 

Whenever necessary, the ToolKit calls your application's routines. For example, if the 
user scrolls the document, the ToolKit tells your program to redraw the changed 
portions of the window. Your program does not need to be concerned with when 
redrawing is required. 

One effect of Clascal is that you can ViTite applications in Heps. You can begin by 
doing the least amount possible, and get an application that does very little, but will 
run. You can then extend your application bit by bit^ checking as you go. This 
characteristic of Clascal makes it easy to extend the capabilities of ToolKit programs, 
even years after the original program. 

The ToolKit •« debugger. Kit Bug, provides run-time debugging of ToolKit Clascal 
programs. It allows you to do performance measurements, set breakpoints and traces, 
tingle-step through your program one statement at a time, and do high-level 
examinations of data objects. 
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The Operefcing Syxtenrh The Operating System frovides an environment in which 
multiple processes can coexist^ with the ability to communicate and share data. It 
provides a file system for I/t) and information $torage^ and handles exceptions 
(software interrupts) and memory management. 

The FUe System provides input and output. It accesses devices, volumes, and files. 
Each object, whether a printer, disk file, or any other type of object, is referenced by 
a pathname. Every I/O operation is performed as an uninterpreted byte stream. Using 
the File System, all I/O is device-independent. The File System also provides device- 
specific control operations. 

A process consists of an executing programi and the data associated with it. Several 
processes can exist at once, and will appear to run simultaneously because the 
processor is rriultiplexed among them. These processes can be broken into multiple 
segments which are automatically swapped into memory as needed. Communication 
between processes is accomplished through events and exceptions. An event is a 
message sent from one process to another, or from a process to itself, that is 
delivered to the receiving process only when the process asks for it. An exception is 
a special type of event that forces itself on the receiving process. In addition to a 
set of system- defined exceptions (errors), such as division by zero, you can use the 
system calls provided to define any other exceptions you want. 

hiemoiy^' m&rtagement routines handle data segments and code segments. A date 
segment is a file that can be placed in memory and accessed directly. A code 
segment is a swapping unit that you can define. If a process uses more memory 
than the available RAM, the OS will swap code segments in and out of memory as 
they are needed. 

PASUB: PASLIB is the Pascal run-time support library. It provides the procedures 
and functions that are built into the Pascal language, acts as the run-time interface 
to the Operating System, and "completes" the 68000 instruction set by providing 
routines for the compiler-generated code to call upon in lieu of actual hardware 
instructions. 

PASLIB routines are called with all parameters passed on the stack. There is an 
initialization routine to initialize necessary variables, libraries, and exception-handlers 
and set up global file buffer addresses, and a termination routine to kill processes. 
You can do four-byte integer arithmetic. Data can be moved^ or scanned for a 
particular character. String manipulation routines include concatenating, copying, 
inserting or deleting a substring, determining the position of a substring, and 
comparing strings for equality. Set manipulation routines let you find set 
intersections or differences, adjust the size of a set, and compare sets for equality. 
There are range-checking and string range-checking routines. Heap routines let you 
allocate memory in the heap, mark or release the heap, check available memory in 
the heap, and check the heap result. I/O routines let you read and write lines, 
characters, strings, packed arrays of characters, boolcans, and integers, ai well as 
check for a keypress or an cnd-of-line, and send page marks. File I/O routines 
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include rewriting, resetting or closing a file, detecting 8j^ end-of-file, reading and 
writing blocks, and get, put, and seek procedures. 

Flo6tlr*g-Point Librenet: The Lisa provides arithmetic, elementary functions, and 
higher level mathematical algorithms in its intrinsic units FPLib and MathLib, which 
ere contained in the file DSFFUB. 

FPLib provides the same functionality a$ the SANE and Elems units on the Apple ] [ 
and ///, including: 

• Arithmetic for all floating-point and Comp types. 

• Conversions between numerical types. 

• Conversions between numerical types, ASCII strings, and intermediate forms. 

• Control of rounding modes and numerical exception handling. 

• Common elementary functions. 

MathLib provides the extra procedures available only on the Lisa: 

• Extra environments procedures. 

• Extra elementary functions. 

• Miscellaneous utility procedures. 

• Sorting. 

■ Free-format conversion to ASCII. 

• Correctly rounded coriversion between binary and decimal. 

• Finaricial analysis. 

• Zeros of functions. 

• Linear algebra. 

QuickL^aw: Virtually all of Lisa's graphics are performed by the QuickDraw unit. 
You car* draw text, lines, and shapes, and you can draw pictures combining these 
elements. Drawing can be done to many distinct "ports" on the screen, each of which 
is a complete drawing environment. You can "clip" drawing to arbitrary areas, so 
that you only draw where you want. You can draw to an off-screen buffer without 
disturbing the $creen, then quickly move your drawing to the screen. 

Text characters are avilable in a number of proportionally-spaced fonts. Any font 
can be drawn in any size— if a font isn't available in a particular size, QuickDraw 
will scale it to the specified size. You can draw characters in any combination of 
boldface^ italic^ underlined, outlined, or shadowed styles. Text can be condensed or 
extended, and it can be justified (aligned with both a left and a right margin). 

Straight lines can be drawn in any length and width, and can be solid-colored (black, 
white, or shades of gray) or patterned. 

Shapes defined by QuickDraw are rectangles, rectangles with rounded corners, full 
circles or ovals, wedge-shaped sections of circlet or ovals, and polygons. In addition, 
you can describe any arbitrary shape you want. All shapes can be drawn either 
hollow (just an outline, which has all the width and pattern characteristics of other 
lines) or solid (filled in with a color or pattern that you define). 
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QuickDraw lets you combine any of these elements into a picture, which can then bi; 
clrawn--to any jcale--with a tingle procedure call. 

Three- dimensional grapMcs capabilities are also available, in a unit called Giraf3D, 
which is layered on top of the QuickDraw routines. Grar3D lets you drew three- 
dimensional objects in true perspective, using real variables and world coordinates. 

The Hardware Irterface-. The Hardware Interface unit lets you access Lisa hardware 
elements such as the mouse, the cursor, the display, the speaker, the keyboard, arid 
the timers and clocks. 

f^iouse routines determine the location of the mouse, jet the frequency with which 
software knowledge of the mouse location is updated, change the relationship between 
physical mouse movement and the movement of the cursor on the screen, and keep 
track of how far the mouse has moved since boot time. 

Cursor routines let you define different cursors, track mouse movements, and display 
a busy cursor when an operation takes a long tinne. 

Screen- cor^rol routines can set the size of the screen, and set contrast and 
automatic fading levels. 

Speaker routines allow you to find out and set the speaker volume, and create 
sounds. 

Routines are provided to handle the different ke^toercfs available for the Lisa, as 
well as the mouse button and plug, the diskette buttons and insertion switches, and 
the power switch. You can find out which keyboard is attached, and set the systerp 
to believe that a different physical keyboard is connected. You can check to see ^ 
what keys (including the mouse button) are currently being held down, look at or 
return the events in the keyboard queue, and read and set the repeat rates for 
repeatable keys. 

Date and time routines let you access the microsecond and millisecond timers and 
check or set the date and time. 

The Staixfard Uhil-. The Standard Unit (StdUnit) is an intrinsic unit providing a 
number of standard, generally-useful functions. The functions are divided into areas 
of functionality: character and string manipulation, file name manipulation, prompting, 
retrieval of error messages from disk files. Workshop support, and conversions. 

The unit provides types for standard strings and for sets of characters, definitions for 
a number of standard characters (such as <CR> and <BS>), and procedures for case 
conversion on characters and strings, trimming blanks, and appending strings and 
characters. 

File name manipulation functions let you determine if a pathname is a volume or 
device name only, add file name extensions (such as ".TEXT"), split a pathname into 
its three basic components (the device or volume, the file name, and the extension) 
put the components back together into a file name, and nnodify a file name given 
optional defaults for missing volume, file, or extension components. 
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Prompting procedures let you get characters, strings, file names, integers, yes or no 
responses, and so Torth from the console, providing for default values where 
appropriate. 

Special Workshop functions let you stop the execution of an EXEC file in progress, 
find out the name of the boot and current procest volumes, and open system files, 
looking at the prefix, boot, and current process volumes when trying to access a file. 

Conversion routines let you convert between INTEGERS (or LONGINTs) and strings. 

The DPrimltives Unit: The lOPrimitives unit provides you with fast, efficient 
text-file input and output routines with the functionality of the Pascal I/O routines. 
It includes routines for reading characters or lines, and for writing characters, lines, 
strings, and integers, plus the low-level routines on which the others are based. 

The Program Comrminlcations Unit: The Program Communications unit (ProgComm) 
provides three mechanisms for communication between one program and another or 
between a program and the shell. The first two infr/olve strings sent from a program 
to the shell; one tells the shell which program to run next, the other is a "return 
jtring" that can be read by the exec file processor to tell an exec file, for example, 
whether the program completed successfully. The third mechanism involves reading 
from and svriting to a IK byte communications buffer, global to the Workshop. Using 
the unit, a program can invoke another program and provide its input tt'irough the 
buffer, without user intervention. 

LitaBug: LisaBug provides commands for displaying and setting memory locations and 
registers, for assembling and disassembling instructions, for setting breakpoints and 
traces to trace program execution, for manipulating the memory management 
hardware, and for measuring execution times using timing functions. Utility 
commarids are also available to clear the screen, print either the main screen or the 
LisaBug screen, change between decimal and hexadecimal, change the setting of the 
NMI key, and display the values of symbols. 
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Vi^wre to Go from Here 

The Lisa development software is not fully documented yet. The following is a list of 
what is available^ some of it only internally, as of this publication. Note that the 
spring-release manuals will be organized differently from the current versions, and 
will incorporate much of the information that is now in the internals documentation 
or in tcparate documents. 

Psscal Reference Manual for the Lisa 
includes: QuickDraw 

Hardware Interface 
Floating-Point Library 

Operating S^-'sterrt Reference t^ianual for the Lisa 

Workshop User's Guide for the Lisa 

Lisa De^'^eJopnrwni System Internals Documents^ ion 
includes: Pascal Run-Time Library 
Standard Unit 
LisaBug 
Floating-Point Libraries 

QuickPort t^plications User Guide* 

QuickPort Frogramrrier's Guide* 

An Introduction to Clascal 

Clascal SeJf'Stud^'- 

ToolKit Reference Manual 

ToolKit Training Segments 

Numerics Manual: A Guide to Using the Apple ///Pascal SANE and Elems Units 
FPLib provides the same functionality as these units. 

MathLib Guide* 

♦These manuals currently in rough draft form. 
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The following compiler commands are available: 



$%*- or $X- 
$C+ or $C- 



$D<- or $0- 

3E filename 
$Hf or $K- 

$1 filenane 



$L filenane 



$L+ or $L- 



SCN- or $0- 
$0V-»- or $0V- 



Allow the % symbol in identifiers. The default is $X-. 

Turn code generation on {*) or off (-). This is done on a 
procedure-by-procedure basis. These commands should be written 
between procedures; results are unspecified if they are written 
inside procedures. The default is $0+. 

Turn the generation of procedure names in object code on (♦) or off 
(-). These commands should be written between procedures; result^ 
are unspecified if they are written inside pirocedures. The default 
is $CM-. 

Start making a listing of compiler errors as they are encountered. 
Analogous to $L filename (see below). The default is no error 
listing. 

Disables handle checking so dereferenced handle: (master pointer;) 
may be ijie6 in with statements, on the left side of assignment 
statements, end in expressions involving procedure calls. The 
default is $»-N-. 

Start taking source code from file filename. When the end of thit 
file is reached, revert to the previous source file. If the filename 
begins with + or -, there must be a space between $1 and the 
filenanne (the space is not necessary otherwise). Files may be $1 
included up to five lev,'ers deep. 

Start listing the compilation on file filenane. If a listing is being 
made already, that file h closed and saved prior to opening the 
new file. The default is no listing. If the filenanrie begins with ♦ 
or - there must be a space between $L and the filename (the space 
is not necessary otherwise). 

The first ♦or - following the $L turns the source listing on (♦) or 
off (-) without changing the list file. You must specify the listing 
file before using $L*. The default is $L*, but no listing is produced 
if no listing file has been specified. 

Suppress register opitimization (-). The default is $0*. 

Optimization limited—use the old (2.0 release) optimization 
mechanism, instead of the new one. The default is the new one. 

Turn integer overflow checking on {*) or off (-). Overflow checking 
is done after all irrteger add, subtract, 16-bit multiply, divide, 
negate, abs, and 16-bit square operations, and after 32 to 16 bit 
conversions. The default is $0V-. 
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Internals 
$R+ or $R- 

$S segnane 

$U filenane 

$L>^- or $U- 

$X+ or $X- 



$SETC 



Tijrn range checking on (♦) or off (-). At present, renge checking i/^ 
done in assignment statements and array indexes and for string 
value parameters. No range checking is done for type longint' The 
default is $R+. 

Start putting code modules into segment segname. The default 
segment name is a string of blanks to designate the "blank 
segment/' in which the main program and all built-in support code 
are always linked. All other code cari be placed into any segment. 

Search the file filename for any units subsequently specified in the 
uses-clause. Does not apply to intrinsic-units. 

Tell the system not to search IKTRINSIC.LIB for units you use (-). 
The default is $Q* — the system searches IimilNSIC.LIB first, 
then your own libraries. 

Turn automiatic run-tinrie stack expansion on (♦) or off (-). 
Run-time stack expansion is the insertion of ari extra 4-byte 
instruction per procedure to ensure that the Lisa's memory- 
managemtent miechanism has mapped in enough stack space for the 
execution of the procedure. With $X- excessive ut^e of the stack 
bv- the procedure could cause a bus error. The default is $X+. 

The $SETC commiand has the form: 

{$SETC ID := EXPR} 

or 

{$SETC ID = E>PR) 

where ID is the identifier of a compile-time variable and E)TO is a 
compile-time expression. EJWR is evaluated immediately. The 
value of DTO is assigned to ID. 

Compile-time variables are completely independent of program 
variables; even if a compile-time variable and a program variable 
have the same identifier, they can never be confused by the 
compiler. 

Note the following points about, compile-time variables: 

■ Compile-time variables have no types, although their values do. 
The only possible types are inieger and boolean. 

• At ariy point in the program^ a compile-time variakfle can have 
a new value assigned to it tiy a $SE1X: command. 
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$linc,$EMX 

$ELJSEC Conditiori&I compiJation i^^ controlled by the $IFC, $ELSEC, ancj 

$EJCC comrrisrids, which are used to bracket sections of soince te^t. 

Whether a pai-ticulsj' bracketed section of a progiam \% conripiled 

depends on the boolean value of a compUe-iime expression, whic*' 

can contairi corripile-iime variables. 

The $ELSEC end $EHX: commands take no arguments. The $irc 
command has the form: 

{$IFC EXPR) 

where E)C^ is a compile-time expression with e boolean value. 

These three commands form constructions similar to the Pascal 
if-statement, except that the $E>CC command is always needed &t 
the end of the $IFC construction. $Ft SFT is optional. 

$IFC constructions can be nested within each other to 10 level:. 
Every $IFC nriust have a matching $E>IX. 

Conipile-time expressions appear in the $SETC corrjmand and in the 
$IFC comiTiend. A compile-time expression is evaluated by the 
coiTipiler as soon as it is encountered in the text. 

The only operands allowed in a compile-time expre-sion are: 

• Compile-tin-ie variables 

■ Constants of the types integer and booleaa (These are also the 
only possible types for results of compile-time expiressions.) 

All Pascal operators ere allowed except as follows: 

- The in operator is not allowed. 

• The i) operator is not allowed. 

■ The / operator is automatically replaced by div. 
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PASCAL 

CODE CRUNCHER'S 

HANDBOOK 

Fred Forsman 



Intrcxiucticxi 

This document explains how to reduce the size of Pascal code by changes 
at the Pascal source level. Thus what will be presented are source 
transformations which result in sernantically equivalent, but smaller 
code. 

While these transformations will produce smaller code, they are unlikely 
to produce code that is "better" in all senses. Sometimes you will be 
trading off clarity for efficiency since typically you will be changing 
what was the first and obvious way of writing your code. On the other 
hand, your code may benefit (and actually become clearer) just from 
ha^'ing been thought about a second time. Nevertheless, if it is given 
that you must reduce your code size, you may find these source 
transformations more palatable (and more maintainable) than rewriting in 
assembly language. 

Please note that this is a living document, that is, no claims are made 
that this is a complete or final list of source transformation 
techniques. New techniques will be added as I find out about them (so 
if you are aware of some transformations not mentioned here please let 
ne know about them). Also, some of the techniques described will be 
lemovcd from this docunent when future compiler optimizations obviate 
the need for them. 







Thanks to Al Hoffman for his invaluable assistance in researching and 
docinenting much of the material presented here. Thanks also to Ken 
Fricdenbach and Rich Page. 
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How to find what code to crunch and how to 
measure your progress 

Given a Pascal unit which you want to crunch, you need to identify the 
procedures which are roost likely to benefit from crunching and you need 
a mechaniSTR by which to measure the results of your efforts. The Pascal 
code Qenerator writes information to the console on the size of the code 
generated for each procedure and the size of the code for the unit being 
compiled. With a compile exec file such as the one below you can 
redirect this information to a filc^ for use in later analysis. 

3EXEC {perform a compile} 

$ { the first parameter (%0) specifies what file to compile } 

$ { if a second parameter is specified, it is used for the output obj 

file, otherwise we default to "W.obj" } 
$ { if a third parameter is specified, the code generator's console 

output is redirected to "%2.text", otherwise default to "g.text" } 
3 { the intermediate file is put in a temp file on -paraport } 
P{Pascal}^ 

-par aport- temp 
$IF %2 <> " 1>CN 

S{Sys-mgr }0{OutputRedirect }%2 . text 
3ELSE 

S{Sys-mgr}0{OutputRedirect} g.text 
3ENDIF 

0{Quit Sys-mgr} 
Gigener at e)-par aport- temp 
$IF XI <> •• THEN 

%1 
1ELSE 

3Ef€IF 

S{Sys-mgr}0{OutputRedirect}-consolc 

OlQuit} 

Once you have the code generator's console output, the first step is to 
identify the easy targets for crunching-, most often these will be the 
larger routines (code size > 250 bytes, or some similar criterion). The 
above exec file can then be used to verify that any changes you make 
actually result in code size improvements. 
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If you are working on code that is not totally new, chances are that it 
has undergone a nunber of major and minor changes. As code is modified, 
"dead" code and variables are often left around inadvertently. These 
unused objects can be discovered and removed by checking the code with 
the various cross reference utilities. (While the Workshop linker will 
remove dead code automatically it will not remove dead variables.) 

For those of you who want to know what the compiler is real J y doing, use 
the DifipObj utility to look at a disassembly of any of the procedures or 
functions you are interested in. 
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How to crunch code: techniques 

Following are a number of techniques for Pascal source transformation. 
The fine print following the description of each technique attempts to 
estimate the potential space savings, the difficulty of implementation, 
and probability of introducing errors. 

1. The first law of code crunching: don't use irv-line code when a 
procedure to do the seme thing exists. The in-line code may be 
faster, but space is more important in the vast majority of cases. 
In order to apply this law effectively you should KNDW WHAT IS 
WKLUPBLE IN T>€ UERffUES, Similarly you should be familiar with 
what the language provides, particularly in the area of built-in 
procedures and functions. 

U&ing existing cod* is purt gtin. TTw tfangtr of doinq so should b« ninintl sinct trw 
co^il«r tnd liDrtxits sfwolfl D* trror fr«« (or at itt&t trmr Doi;$ win b« rtcoqnizeo and 
fixed sooner tnar your privet* oode wfiicn is txerciztd less often). 

2. An extension of the above law is the creation procedures which 
perform code sequences which are repeated often in your code (minor 
differences can be handled by parameterization). One name for this 
technique is "factaring". Use of parameters can degrade the 
optimization if the size of the code being factored is small. On 
the other hand, if introduction of a parameter will allow sharing 
of a long sequence of code the extra overhead should be well worth 
it. ft word of warning: check to see whether your factoring really 
paid off — the code being factored out should not be smaller than 
the procedure call (and any parameter passing) that replaces it. ft 
point to note is that factoring of even single statements can be 
fruitful, for example: 

ft[F(X)] :» ft[F(X)] -► 1; tecomes INCft; 

Factoring can &e % BIG win in neny cases, often sawing nore tnn car De ecnir.'ec &y eny 

other tecnniQue. so it often peys to look tnrougn your cooe for comon cooe sequences. 

Difficulty end likeiyfxod of errors are lov, but increase if peraneters nust De 
introduced . 

3. Make procedures that are 50-100 lines long - around 300 bytes of 
code - to optimize allocation of variables to register. Shorter 
routines do not have enough occurrences of variables to make 
register allocation worthwhile, and longer routines create more 
opportunities for register optimization than there are registers 
available. 

Tr« efiount of inprouenent losing this tecfviique is highly variiDIe. Difficulty is 
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nooertte; likelyrtooo of errors is low. 

4. Avoid the use of global scalar (1 to 4 byte} variables whenever 
possible - global variables arc never put into registers. 
Techniques applicable here include: 

4a. Assign a frequently used global variable to a local variable, and 
change all references to be the local quantity. Caution! Beware of 
saving and restoring the global quantity around procedure calls 
that might access the global quantity. 

The amount of improvement will be two to four bytes per reference, 
with the greatest gain appearing on assignments like A:»A*1. There 
is an overhead cost to assign the local and save registers (4 to 14 
bytes). Improvement will not occur if the registers have already 
been assigned to locals that ere used more frequently than the 
global is. 

The wiount of iwpro« Ji > w >t <jsinQ tnis tecfrtique is noted tbo^. Difficulty is low: 
liktlynooo of errors is hiif^. 

4b. Further leverage on (4a) can be obtained if the same local 

temporary variable is reused in different parts of the procedure 
for different global variables. In this way, less frequently used 
globals still have a chance for optimization into registers. 

Ifpro ^cwen t is tvo or nore oytes per tooition&i reference, less a Dytes per nev gioo&i 
•ssigneo. Difficulty is nodertte; likelyriooa of errors is e*.«n higrtei then (oa). 

4c. Another, more reliable way of conv.'erting a global to a local is to 
pass the global variable as a var paremeter to the routine. 
Parameters are treated like local variables. 

IrproMcnent is tvo or nore Dytes per reference, less ^10 oytes ptr eooitioneJ perencter, 
suDject to register coppetition «s noted «Dove. Difficulty end liicelynood of errors vith 
ver peraneters is low. 

4d. hove a large main program bocfy into a main subroutine. Move all 
global variables that are only accessed by the main program into 
the subroutine. 

Iwpr ou awi n t is 9erteriLlly smil, sinoe the mir\ program Dody is usueily a tmll pert of the 
totel oooe. Difficulty end likelyhood of errors ere low. 

5. In a moderate to large procedure, the nimber of scalar (1 to 4 
byte) local variables (and parameters) should be kept to a minimum, 
since there is competition for registers. Briefly used integer 
quantities and loop variables, for example, should all be stored in 
the same variable (which might be appropriately named "tempint" or 
some other generic name). Beware, of course, that the variables 
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usages are never simultaneous. 

InproM«nent, for e«:^ aaoitiooAl locaJ wiaoie tfmx o«.*erload& m existing register, is 
typically two Dytes per reference. Difficulty is low; iikelynood of errors is wodereite. 

fK/oid, at all costs, passing frequently used local variables as var 
paremetcrs or using them in nested procedures. (Also for 
frequently accessed paran^eters.) These actions inhibit the value 
from being located in a register. Replace passing as a var 
paratnater with assignment to a new local variable, passing the new 
local, then doing a reverse assignment. Replace nested pi ocadure 
usage of the variable with passing the variable as a non-var 
parameter, use of the parameter inside the subroutine, then, if the 
nested procedure changes the value, copy the parameter into a new 
variable at the end of the subroutine copy it back into the main 
local variable after the call. The following example illustrates 
optimization of nested usage of A and B: 



PRCXXDURE UPPER; 
VAR A, B: INTEGER; 

PROCEDURE LOWER; 

BEGIN 

A :« B; 



com-erts to^> 



BO', 

BEGIN 

LOWER; 

(other statements} 

{frequent uses of A and 8} 

END; 



PROCEDURE UPf=CR; 

VAR A, B,TEr^: INTEGER; 

PROCEDURE LOWER ( A, B: INTEGER' 

BEGIN 

A :« B; 

TEhP :- A; 
ETC; 

BEGIN 

LOWER; 

A :- TE^P; 

(frequent uses of A and 8} 

ETC; 



Note that, in the above case, if A is not frequently used in the 
subroutine, it could be eliminated as a parameter and the 
assignment could be made to TEhP directly: 

PROCEDURE LOCRCB: INTEGER); 

BEGIN 

lEtf> :- B; 

END; 

A final added technique that can be used with procedure calls is 
to pass the local as a non-var parameter, change the procedure to a 
function, and assign the returned function result back to the local 
variable. 



PROCEDURE PROC(VAR N: INTEGER); 
PROCEDURE LXAL; 

tecames — > 



FUNCTION PROC(N:INTEGER) -.INTEGER; 
njNCTION LXAL ( A. B: INTEGER): INTEGER 
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PROC(A) ft :s PROCCft); 

LXAL; ft :» LXAL(ft,B); 

whe re ft is a frequently used local variable used as a var parameter 
to PROC, and used in nested procedure LXAL. This method, although 
limited in application, is elegant because no temporary-variable 
assignments have to be inserted. 

Inpro'.^fient is two or mrt Dyt«» per refertnce of tf»e frequently used werieDle in the «idn 
proceoure, less 2-8 Dytes per extra tssigment statenent, suDject to register oonpetition 
ts notec 900^. Since cnis optiniz&tion cen pe ippliec to v«ry frequently usee vtriacies 
thtt ere eCMnocneo Dy trte conpilcr, lerge optinizttions of up to 40 or fiore pytes are 
possiPle in large proceoures. Difficulty and likelyrtooo of errors vitn var paramter 
supstitution is low-, difficulty wa likelynooo of errors vitn nested proceoures is 
nodcrate to ni^. 

7. Don't use the set construct to check ranges; instead use 
comparisons against the upper and lower bounds. 

Getting rid of tne set construct is a BIG s«^ings (typicaJly ar»nd 30 pytes for tne usual 
Oouoie-«ndeo range cneck). Difficulty is nininai, as are tne charces of error. 

8. Do not pass mult i -word (more than A bytes) data structures as 
non-var parameters unless necessary. Change them to VAR 
parameters. 

Inprowefwnt is 12-18 Pytes sawed py not hawing code to copy tne parameter into local 
storage in tne called proceoure. Difficulty is lov; luclyhood of errors is nooerately 
low. 

9. Replace FOR loops with WHILEs and REPEftTs. The equivalent REPEATS 
and WHILES are typically 8 to 10 bytes shorter, even with the 
explicit loop variable initialization and increments. REPEATS are 
•tore efficient than WHILEs which are better than FORs. Sometimes 
the savings will be greater depending on the contents of the loops 
and the termination condition. 

SiMings are typically 8 to IQ Pytes per construct. Difficulty and chances of error are 
smll (just take care to get your termination condition correct — Pevare of off-Pynxte 
errors). 

10. Convert array indexing in loops to pointer arithmetic, when the 
total number of indexing operations can be reduced. For example 

FOR I :« 1 TO 100 DO A[I] :■ 3 ccm''erts to 

P :« iA; {A's origin is 1; P is typed as *A[I]} 
FOR I :« 1 TO 100 DO 
BEGIN 

P-^ :« 3; 

P :« POINTER(0RD(P)*SI2EOF({ft's element type})); 
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EhD; 

inprty^tfitnx. is yp to 18 Dytes p«r index operation (nor« vhtn rrtt «my origin is nonzero 
or trw erray elenent size is not Dyte: s«wif>g$ can De even higher on packeo structures if 
tnt progremei is viuing to «3Q t f«v nore contortions); difficulty is moeriLte: 
liktiyrooc of errors is nooerete. 

11. IPs without ELSE parts that have a conjunctive conditional (IF a 
AND b THEN ...) arc more efficiently expressed as nested IPs (IF a 
T>£N IF b T>€N ...). In effect, this implements your own "short 
circuit" boolean evaluation. 

me swings is typically a Dytes for eacfi t*€ eiininatcd. very ttsy to inpic^ent. Just 
oon't try it on ORs. 

12. Avoid packed structures whenever possible. Remember, packing is 
only useful when a large amount of data has to fit in a limited 
space — It does not decrease the size of the code. 

lrpro^*enent is nigniy vtriiDie ana can oe vast. Difficulty is lov; likeiynooo of errors 
is lov if trici<s like (lO) do not pervade tne code. 

13. Repetition of expressions in the code should be removed by 
pre-assigning a common expression value to a temporary variable. 

Ii*f>rovancnt is highly t/ariaoie. Difficulty is nodarate: likeiyhood of errors is low. 

14. Convert procedure parameters to global or local variables when the 
same actual value is always passed to the subroutine, and when 
there is no recursion. 

lr^;troM«Ment is 2-4 bytes par parameter sa^ed. Bavarc of creating upir^ci maartsixnq of 
'not' varieolcs however (see (6>>. Difficulty is nooerate; likelyhood of errors is lov. 

15. When groups of local or global variables are commonly passed 
together as parameters, and are not 'hot* (assigned to registers), 
they could be combined into a single record, which would then be 
passed as a var parameter to the subroutine. 

I tyi ' ovewej ' i t is a Oytes per paxaneter, with m overhead of 8 Dytes (warning, the called 
procedure nay grow in size if it already uses aii registers). Difficulty is noderate; 
litcelyhood of errors is low. 

16. If you have several instances of the same string constant in your 
code declare it as a CONST, otherwise the compiler will store 
Rultiple versions of the same constant. 

The s«.;ings depends on tr» size of the string and the nunDer of occurences. Easy to do. 

17. Turn range checking off after a sufficient amount of testing has 
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occurred. 

lppTovef»ent is a-d Dytes per re^rence or tssig^^ent of t rtn9e-cftec*<ed quantity; 
difficulty i* too low: liktlytiocc of errors is fturly hign since e sufficient wojnt of 
testing neuer occurs, cortsioer mking tnis cnetnqi on t proceoare-oy-p''ooeoare confioence 
ltv«l Dtsis. 
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How to crunch code: some case studies 

The following section presents some case studies demonstrating some of 
the techniques presented in the previous section. These examples are 
intended to demonstrate how some of the transformational techniques are 
typically used and how a whole series of transformations may be applied 
to a single body of code. The main purpose of the examples, however, is 
to give a sense of the thought processes involved in crunching code. 

If you have any good "before" and "after" examples demonstrating how, fat 
code was reduced please feel free to contribute them. Your efforts may 
provide ideas and inspiration to others. 

CASEl: 

Following is the original form of the body of a routine (SUUpCh in the 
StdUnit) which converts lower case characters to upper case. The code 
size for the original routine was 94 bytes. 

IF Ch IN ['a'..'z'] Th€N 

SUUpCh :- Chf5 (ORD (Ch) - 32) 
ELSE 

SUUpCh :- Ch; 

The code above was replaced with the following, which replaced the set 
range test with two comparisons. The code for this version of the 
procedure was 66 bytes — a savings of 28 bytes (about 30%, or actually 
more, since these sizes include the overhead for the procedure and the 
assignment statements). The moral here is that SET OPERATIONS ARE 
E>a3ENSIVE. 

IF ('a' <= Ch) AND (Ch <= 'z') THEN 

SUUpCh :« CK? (ORD (Ch) - 32) 
ELSE 

SUUpCh :« Ch; 

The following change was then made which saved another 2 bytes (bringing 
the procedure size down to 64 bytes) by getting rid of the branch for 
the ELSE logic on the IF statement. 

SUUpCh :« Ch; 

IF ('a' <« Ch) AND (Ch <« 'z') T^CN 
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SUUpCh := ChR (ORD (Ch) - 32): 

A further change — breaking the ft€ in the IF into nested IPs — 
resulted in a 4 byte savings, leaving the procedure size at 60 bytes (an 
improvement of 36% over the original 94 bytes). In effect this is 
performing "short circuit" boolean evaluation at the source level. The 
source for this version is as follows: 

SUUpCh :« Ch; 
IF 'a' <« Ch 1>EN 
IF Ch <« 'z' THEN 
SUUpCh := CHR (ORD (Ch) - 32); 

Note that this last transformation would not have worthwhile if we had 
not alreacJy removed the ELSE part of the IF since the nested IPs would 
have required two ELSEs. 

Below is the bocty of the original version of SUUpStr which uppercases a 
string. 

FOR I :• 1 TO LENGTH (S*) DO 
S^[I] :« SUUpCh (S"[I]); 

The following version — conrvertmg the FOR loop to a WHILE — saved 8 
bytes. 

I - 1; 

UHILE I <« LENGTH (S**) DO 
BEGIN 

S"[I] :« SUUpCh (S^I]); 
I :« I •► 1; 
EhD; 

A further, time-oriented optimization would be to perform the 
upper-casing in reverse order with the call to LENGTH outside the loop, 
which also simplifies the termination condition to a test for zero. 

A/i SSiCfe: When appropriate (when tr« loop booy win be txecutto tt letst orct) « repeat win 
smf€ •notntr 2 bytts. I ttsted the trve« cor&tructs vith xtcrtt ttst prooeoures (ti, t2, t3) ts 

follows: 

procedure tl; 
vtr 

j : integer: 
begin 
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for j ;» 1 to i 00 

foe :s bW; 
tfW; 

procedure t2; 
v«r 
j : inttger: 

J :. 1; 

uhilt J <■ 1 do 
be^in 
foo := bar: 
j :s j * 1: 
tno: 
eno: 
proc«3U7t t3; 
vtr 
j : int*9cr; 

repwt 

foo :s D«r; 
j :« j ♦.!: 
irtU J > X; 
tnO; 

T2 (yHILE) s«ped 8 Dytes over Ti (FOR), ana TZ (REPEAT) say«a lO Oytes over Ti (FOR). 

CASE 3: 

ft series of small transformations was applied to the following segment 
of TrimLeading (which trims leading blanks and tabs from a string). 

FOR I :« 1 TO CRD (S"[0]) DO 
IF [S^ll] . SUSpace) OR (S^I] » SUTab) THEN 

{ skip over leading spaces } 
ELSE 
BEGIN 

DELETE (S", 1, I - 1); 
EXIT (TrimLeading); 

ETC; 

{ we fell thru — either '' or all blanks ) 

The first change was to change ORD (S^[03) to LENGTH (S"), which saved 4 
isytes. (I must have thought I was being clever in the original.) 
Calling the built-in function saves code by leaving the array access to 
the built-in. 

The next change was to get rid of the ELSE in the FOR loop by reversing 
the sense of the condition (which resulted m the code below). This 
last change resulted in no code size change since a short branch was 
removed but another logical operator was added. But this prepared us 
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for some subsequent chariges. 

FOR I :« 1 TO LETCTH (S") DO 
IF NOT ((S^[I] = SUSpace) OR {S^[l] « SUTab)) ThEN 
BEGIN { delete leading as soon as we find a nort-blank chei } 
DELETE (S^ 1, I - 1); 
EXIT (TrimLeading); 

ETC; 

{ we fell thru — cither ''or all blanks ) 

The next step was to apply de Morgan's law (remember your boolean 
algebra?) to simplify the conditional to the following form which saved 
2 bytes by reducing the nimber of boolean operations. 

FOR I :« 1 TO LEhGTH (S") DO 
IF (S^I] <> SUSpace) AND (S'[l] <> SUTab) ThEN 
BEGIN { delete leading as soon as we find a non-blank char ) 
DELETE {S\ 1, I - 1); 
EXIT (TrimLeading); 

EhD; 

{ we fell thru — either ' ' or all blanks } 



Now we have converted the conditional into a form in which we can apply 
our short-circuit evaluation transformation by converting the AND into 
nested IFs, which saves another 4 bytes. 

FOR I :« 1 TO LENGTH (S") DO 
IF (S'[I] <> SUSpace) THEN 
IF (S'^il] <> SLTTab) ThCN 
BEGIN { delete leading as soon as we find a non-blank char } 
DELETE (S", 1/ I - 1); 
EXIT (TrimLeading); 

ETC; 

{ we fell thru ~ either ' ' or all blanks ) 

Finally we convert the FOR construct to a WHILE which saved another 8 
bytes. 

I :• 1; 

WHILE I <« LENGTH (S") DO 
BEGIN 

IF S*[I] <> SUSpace T^CN 
IF S*[I] <> SLTTai) ThEN 
BEGIN { delete leading as soon as we find a nor»-blank char ) 
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DELETE (S^ 1, I - 1); 
EXIT (TrimLeading); 

E^D; 
I :« I * 1; 

{ we fell thru — either ' * or all blanks } 

CASE 4: 

The following is applicable only to programs using WRITES and V*?ITELNs, 
but the general technique of factoring can be applied anywhere. The 
section of code below prints out the defaults (voline, file name, and 
extension) for a file name prompt. 

IF DefVol <> '• ThCN 

WRITE ('[', DefVol, '] '); 
IF DefFN <> " ThEN 

WRITE ('[', DefFN, '] '); 
IF DefExt <> " THEN 

WRITE ('[', DcfExt, '] '); 

The following factoring out of the expensive ^ITZ operations resulted 
in a savings of 168 bytes. 

PROCEDURE WritaOefault (DefaultValue : SUStr); 
BEGIN 

IF DefaultValue <> " TVCN 
WRITE ('[', DefaultValue, '] '); 

WriteOefault (DefVol); 
WriteOefault (DefFN); 
WriteOefault (DefExt); 

CASE 5: 

"Factoring" of common code does not always pay off. Following is an 
instance of how space was saved removing factoring. The SUStrToInt 
conversion routine had an internal procedure called BogusNurnber which 
set the value of the estate parameter to the appropriate error return 
code and then exited from SUStrToInt: 

PROCEDURE BogusNumbcr (CS : ConvNState); 
BEGIN 
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estate := CS: 
EXIT (SUStrToInt); 
ETC; 



BogusNiinbcr was called 6 times in the original SUStrToInt. By replacing 
the calls to BogusNunber with BEGIN CSt ate :» ErrCode; EXIT(SLStrToInt) 
EhD we got rid of the 50 byte BogusNimber routine and the size of 
SLStrToInt when down from 500 bytes to 380 bytes, a total saving of 170 
bytes. The moral here is to OCCK YOUR FACTORING TO SEE THftT IT REALLY 
PAYS OFF. 



The Last Whole Earth 
Text File Format 

Fred Forsman 

This is the latest proposal for the definition of text files. In creating 
this definition I had thoree (not always convergent) goals in mind. 

1) Text files should support Pascal's model of files of type 
TEXT as well as possible — that is, if a file was 
•written by Pascal WRITES and WRITELNs it should be a 
vislid text file with as few exceptions as possible. 

The intent here is to gi'je reasonaDle wpport to Pascal's TEXT necnanis^ as 
it is defined in tr* ]irtgj»g& — wfiile tf* leriguage n&^,e£ rio stt^tenent stout 
xtK forn of TEXT file*., or»fe wou)cJ expect tr»&t files written vithcjt errors 
will result in valio te^t fjies of so»ne sort. This is not to ss.y triat sli 
tcois sr»ouia supfcrt every per<^rse file tnat cari De genereteo vit PKC-ei 
te>:t l,^. At ft Minirtjn. hcve^'er, trie Pasoe.l run-ti«e*sy<ter. should &e as 
acc-op^i'ds-tin.: bs piDsiiMe in it£ sijpport of Pascal text i,v, and tffe editor 
sTiOijld sfouid nai'^e sinilaj' efforts sinoe it is tr»£ (Se^'ice nost often used to 
inspect text files (wfittrifer rcrmil or fcUirrafit). 

2) To make the processing of text files as straight forwai-d 
and efficient as possible. 

3) To be cofTipatible with the UCSD text file formats in the 
Pascal systems on the Apple II and Apple ///. 

T^e follo'a'ing definition follow* the iX-SO text file fornat fairly closely. 
Tr»e orH£ or t/.'o cteviatiorts oori't pc-se e 'jery serious trjeat to coiipetit'ilitv 
sihoe the-y irwol'^ aonornaJ cases which ere not likely to be enoxntered or 
gerierated in norrj&i pr&:tice. 

The following definition involves compromises to all of the above goals. The 
determination of which goal has been most violated I leave as an exercise to 
the reader. 

The definition of a text file: 

■ A text file is a sequence of 1024-byte Daaes . 

• One 1024-byte header page is present at the beginning of 
the file. This is not considered to be part of the 
actual contents of the text file, but is used by the 
editor to store formatting information, etc. Am/one 
creating a header page should do so with nulls in all 
1024 trytes, unless there is a good reason to do 
otherwise. (The format and interpretation of the header 
page will be described in a forthcoming document.) 
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Each text pag e (i.e... those following the header page) 
containi:- sorrte number of complete lines of text and is 
filled with null chai-acters (ASCII 0) after the last 
line. 

The Pascal rorvtip»e system should ensure tn*t ell text files end with & CR 
when CLJdSEd, in pajrticulei, cfeeling with the case ^Jt\^^ the lest action 
before the cuose was a WITE instead of a VRITELN. Sinilarly, the rtjvtif»e 
systen should also ensure that pages terminate vith CRs even if inordinately 
lOTig lines are vritteri Dv a series of wiTts vitrcut any writelns (hcve<.>er 
deterwinihQ s^^en to insert a CP can De a tricky issije).* (For wore on 
related iss'jes, see trie following tvo points.) 

The end of a text page must terminate with at least one 
null. For simplicity, the first instance of a CR-null 
sequence will signal the end of the page. 

1^ -J coTisequerice of tnis sinp-lifying ass'jnpti'DTi, a VRITEU>< followed Xij a 
'/*iITE (CHR (0)) will inao.'ertently terniriate trie current page, but anyone 
witing nulls to * ta;».t file is iwiogi in a state of sin ©rvd de>ej-v,^s vr(*.t 
they get. 

TO be oTi the safe si 05, 'XKJe •ieMin-j with text files at trie BLDCKREAD le^->el 
should rnjt a»sune that * firwi CR-mjll always exists, pwrf;i rig sure not to ruri 
off the end of page dijffers. Ojr tools srwjld not blow up xx\ invalid inpjt. 

ft line is a sequence of zero or more characters followed 
by a Cf<. A line may be "ai'bitrai-ily long" (1023 bytes 
long,, counting the CR with roorri for a terminating null 
at the end of the page) but programs (such as development 
s^/stern tools) may choose to consider as significant only 
the first /v' characters (where A' is a reasonable and well 
doc'/fiented nijmber, i.e., either 132 or 255). 



jxa p«sc«a rjh-tiHe svsten should ai low the reading and writirig of 
arbitiaiily long lines. The contents of a long line shcjld be obt8.ir»3Dle 
via a series of REftDs. The artior. of RE«)LN should be to read past the next 
CR. retui-nirc? an IORESLilt varning val'je if charairters are skipped in the 
process . " 

Support of 'aroiti-arilv long" lir«s should not be viewed as a trireat to tool 
iF^plenentors . Tools may r»aOe reasonable restrictions on wTiat text files 
tT/ey cTioose to accept, as lorig as tne-y dorrt blow up ofi otrier text files. 
Tools nay chocrse to igriore the excess ori urjeasonat'ly lorig lines, give a 
warning,' or signal an error arid aDort processing. 

ft sequence of spaces at the beginning of a line may be 
cofTipressed into a two-byte code, namely a OLE chaiactez 
(ftSCII 16) followed by a byte containing 32 plus the 
number of spaces represented. 

A null text file (i.e., one which has no contents — as 
might be created by opening a file and then closing it 
before anything is written to it) consists of only the 
1024-byte header page. 
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Pascal's Packing Algorithm 



Packed Records 



Packed records ore very expensive in terms of the number of bytes of code 

generated by the compiler to reference a particular field. In general, you 

should avoid packing records unless there will be many more instances of the 

record than there are references to it. Packed records arc pecked in the 
following bizarre way: 

1. Fields flxe packed as tightly as possible without crossing word boundiies, 
starting at the low-ordered bit of the first byte. (Note that in a 
packed record, a character or 0..255 fits into a byte.) Records will 
always occupy either one byte or an even number of bytes. 

Note that only scalar values and subranges are considered peckable; 
everything else must go on a word boundry. 

For example, 4 booleans and a set are packed as follows: 



BYTE 1 



7 



8YTf 2 



7 



riTE 3 



7 



rrTE A 





— 


— 




A 


I 


7 


1 
































set 



















2. Any empty bytes are filled by moving the previous field into the empty 
byte if: 

- The field fits into a byte. 

- The field was not previously on a byte boundry. 



BYTE 1 



7 



BYTE 2 



7 



BYTE 3 



7 



BYTE A 



^ 



I A 













set 



3. ftny field that fits in a byte or word and does not share that space with 
other fields is now designated "unpacked". 

Any field that is still considered "packed, *' and is closest to the high 
end of a byte or word, is moved to the high end of that space. 



BYTE 1 



BYTE 2 



BYTE 3 



BYTE A 



3 












2 


1 


















4J 












set 





















A. The last field is treated after steps 2 & 3 have been completed on the 
other fields. 
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5. Finally, bytes containing packed fields are flipped (bits reordered). 
BVTE 1 ^ , ftm 2 ^ , rjTE 3 ^ , byte 4 



7 



7 



7 



l|2| |3 



4 













set 



The following is a (slightly) simpler description of what appears to happen 
vrhen packed records are packed, if you don't need to know the actual process. 

1. Fields are packed as tightly as possible without crossing word boundries, 
starting at the high-ordered bit of the first byte. 

All packed records take up either one byte or an even nunber of bytes. 

Only boolean or subrange types can be packed; all other types start on 
word boundries^ so steps 2 and 3 only apply to these types. 

2. If a byte would be left empty (so the next field can start on a word 
boundry), and there is more than one field in the previous byte, the lest 
(low~ordered) field is moved into the empty byte. 

3. The last (low-ordered) field in any byte with unused space is moved to 
the low end of the byte. (This happens even if it's the only field in 
the byte.) 



Unpacked Records 

Fields of unpacked records are packed in order, starting on word boundries, 
except for booleans and subranges that can fit in a byte. Values that don't 
take up a full byte or word will be packed at the low-ordered end of that 
space . 

The whole record will take up either one byte or an even nunber of bytes. 

For example, a record containing a subrange of 0..15, two integers, and a 
boolean would be packed as follows: 



Bvn 1 











0..15 



avTE 2 



•VTC 3 



integer 1 



avTE 4 



BVTC 5 



Integer 2 
— I ii_ 



syrt 6 



BYTE 7 















— 


6 



BSTC 8 
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Pscked Arrays 

Packed exrays are also code-expensive, except for packed arrays of char. 
(These are treated as a special case/ and the code associated with them is 
compact . ) 

The number of bits per element In a packed array is the smallest of 1,2,4,8 or 
16 bits that will accommodate the element. For example, a subrange of colimn 
A requires the number of bits per clement in colunn B: 



-£- 


«B- 


0..1 


1 


0..2 


2 


0..3 


2 


0..4 


4 


0..10 


4 


0..20 


8 


0..255 


6 


0..39!> 


16 



Booleans arc pecked one boolean per bit. The packed array as a whole must 
occupy an even niinber of bytes. 

fi packed array[1..5] of boolean would be packed as follows: 



BYTt 1 



r«Tt 2 









5 


4 


3 


2 


1 






















A packed array [1.. 5] of [0. .6] would be packed as follows 

BYTE 1 « « rni 2 ^ , BYTE 3 



7 



7 



7 



<2) «(1) 



e(4) I a(3) 



■— — —> — i__i___ii__ 



BYTE 4 



" " i I 

~»B MMM ^_M 



You can use the Si operator to poke around inside any packed value and thereby 
discover what the packing algorithm (probably) is. 

Signed Subranges 

Signed subranges (e.g. -5.. 14) are packed in packed types (unlike UCSO Pascal, 
which won't pack them). The minimum field size for a signed subrange is the 
nlninuA niinber of bits needed to represent any nunber of the subrange in two's 
complement form. 

The minimum field size is then subject to the rules for a particular packed 
type. For example, though -1..2 only needs three bits, if it's in a packed 
array, it will take up four (see ^^t table). If it's in a packed record, on 
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the other hand, it might take up only three bits, or it might use a whole 
byte^ depending on what's packed around it. 



HDTE 

A variable of type -127.. 128 takes up a fyte. 
A variable of type 0..255 takes up a word. 
A variable of type char takes up a word. 
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PASLIB Procedure Interface 

(Workshop Release 1.0) 

PftSLIB is the Pascal run-time support library. It providej the procedures end 
functions that ere built into the Pascal language/ acts as the run-time interface to 
the Operating System, and "completes" the 69000 instruction set by providing routines 
for the compiler-generated code to call upon in lieu of actual hardware instructions. 

The interface to PftSLIB is very tightly coupled with the Pascal compiler, and 
is very likely to be changed to improve performance and reduce code size. Fox 
this reason, only call these routines from assembly language if you absolutely 
and positively have to; stay in Pascal as much as possible when dealing with 
PftSLIB. Most of these routines support the Pascal built-in procedures, which 
are described in detail in the Pascal Pe faience Manual. 

There are a few conventions for using these routines, which must be follo^/ed 
to ensure correct results and successful execution. All the routines are 
called with pararrteters passed on the stack. The parameters are pushed onto 
the stack in the order of the parameter list shown in each routine. 'ST.L' 
indicates a four-b^'te parameter, 'ST.W two-byte, ' ST .B' one-byte (stored in 
the upper byte of a word), and 'ST.S' a set. The parameters passed will be 
popped by these routines before return. The function results, if any, will be 
returned on the stack after the parameters are popped out. Note that the 
functior»-type routines do not expect room for the function result to be 
reserved on the stack before the call, ftlso note that these routines do not 
check for room on the stack; the caller must guarantee enough room on the 
stack for saved registers. The caller should follow the Pascal procedure 
preamble code for expanding the stack before calling these routines. Standard 
register preservation conventions are followed except in the routines 
indicated. Refer to the k^orkshop User's Guide for the usage of the special 
registers and the stack frame allocation. 
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1. Initialization and Termination Routines: X_BEEIN, \END^ \.INIL \.TERM 

None of these routines have parameters, return values, or destroy any 
registers. 

Every main prograrn must have the following beginning and ending sequences 
calling these routines: 

JSR ^_BEGIN ; beginning sequence 

LINK ft6, /f$axx) ; no-op for LisaBug, to look like standard module 

head 
nOVE.L (A7)+, ft6 

LINK A5, il^$0000 ; set up global frame for main program 

SUBA.L $0010(65), A? ; variables for units, etc. passed by loader 



JSP % INIT 



main program code goes hexe 



3SR X TERM ; ending sequence 

ijrCK a5 

JSR %_END 

RTS 

LJt^ILK A6 ; no-op for LisaBug, to look like standard modu''' 

tail 
RTS 

Note that the size of the program global variables allocated to the loader 
is offset -►IS from register AS. 

^♦_BEGIN - Beginning routine. Currently a no-op; reserved for future 
extensions. 

^_END - Ending routine. Currently a no-op; reserved for future extensions. 

VINIT - Initializes PftSLIB internal global data for each process: 

1. Sets up an f-line trap routine, which signals a "sys_terminate'* 
exception if an f-line trap is encountered in the user code, 
terminating the program. 

2. Sets up global input and output file buffer addresses. These 
buffers are used for screen, keyboard, exec files and output 
redirection. The address locations arc fixed on the stack: the 
input buffer address is offset -t-S from register A5; the output 
buffer address is offset -►12. They are set up to point to global 
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file buffers in the sheared data area of PftSLIB. 

3. Initializes the OS exception handlers. 

A. Initializes the Pascal heap local variables. 

NOTE: The %_INIT routine will restart at step 5 if the calling process 
is a resident process. 

5. Initializes the P^LIB local variables. 

6. If the floating-point library lOSFPLIB is linked, it is 
initialized. 



t;t_TERM - Terminate. If the process is resident, it jumps to step j of 

%JLHIT (see above), if not, it calls the OS routine "Hit_End" to 
terminate the process. Control does not return after this cell. 



2. Integer ftrithrtetic Routines: XIJ1IL4, XIJ)IV4, XIJC04 

^_MJL4 - Multiply two 4-byte integers 

Parameters: ST.L - ftrguftent 1 
ST.L - Argument 2 

Returns: ST.L - Product 

Registers used: All registers are preserved. 

The multiplication algorithm is as follows: 

-argument Ts upper word is multiplied by argiment 2' s lower word 
-argument 2's upper word is multiplied by argument I's lower word 
-these two products are added, ajid the sum is put in the result's 

upper word, 
-the two arginents' lower words are multiplied, and this value is 

put in the result's lower word. 
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%I_DIV4 - Divide two 4-byte integers 

Parameters: ST.L - Dividend 
ST.L - Divisor 

Returns: ST.L - Quotient 

Registers used: All registers are preserved. 

The division is performed by subtreicting the dividend from the 
divisor 31 times (for each of the 32 bits except the sign bit). 

%l_yCOA - Reffi&inder frorn the division of two 4-byte integers 

Parsffieters: ST.L - Dividend 
ST.L - Divisor 

Returns: ST.L - Rernainder 

Registers used: All registers are preserved. 

The division is perfonried in the sarie way as: %I_D1V4, above. 

3. Data Move and Scan Routines-. XJCVEL, XJfMJR, X^HLLC, XJCPME, XJCftfi 

5i_M0VEL - Moveleft 

Parameters: ST.L - From Address 
ST.L - To Address 
ST.W - Number of bytes to move 

Returns: — 

Registers used: DO^ Dl, D2, fO, Al, ft2 

If the number of bytes to move is 7 or less, they are moved a byte 
at a time. If the source address +2 1$ the destination address, 
the data is moved one word at a time. If there are more than 7 
bytes to be moved, then data is moved a long word at a time. If 
the ending address is a byte address,, the trailing byte is moved. 
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^.^MOVER - Moveiight 

Parameters: ST.L - Frorn Address 
ST.L - To Address 
ST.W - Number of bytes to move 

Returns: — 

Registers used: DO, AO, ftl, ft2 

Data is moved one byte at a time. 

^♦.FILLC - Fillchar 

Psrarfieters: ST.L - Address to fill 

ST.W - Number of bytes to fill 
ST.W - Fill character 

Peturns: — 

Registers used: DC), Dl, AO, ft2 

Fills the address with the given character one byte at a time. 

>._SCANE - Scan equal 

Parameters: ST.W - Length to scan 

ST.W - Character to scan for 
ST.L - Address to scan 

Returns: ST.W - The position of the character (0 being the 

first) 

Registers used: All registers are preserved. 

Scans the string for the given character, one byte at a time. 

Note that "Length to scan" can be negative, and the scan will go 
in the lower address direction. 
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%^^iW - Scan not equal 

Par erneters: ST.W - Length to scan 

ST.W - Character to scan for 
ST.L - Address to scan 

Returns: ST.W - The first character position that is not equsl 

to the character to scan for (0 being the 
first) 

Registers used-. All registers are preserved. 

Scans the string for the first character not equal to the given 
character, one byte at a time. 

Note that "Length to scan" can be negative, and the scan will go 
in the lower adoress direction. 



A. String Manipulation Routines-. X^CAT, \POS, ^S^P^, XJDG-. VINS 

All the string manipulation routines are performed one byte at a time 

^_CAT - Concatenate 

Parameters: ST.L - Address of 1st string 
ST.L - Address of 2nd string 

ST.L - Address of Nth string 
ST.L - Address to put result 
ST.W - N 

Returns: — 

Registers used: All registers are preserved. 

Copies all the given strings to the result string. 
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%_POS - Position of one string in another 

Pecrarfieters: ST.L - Address of substring 
ST.L - Address of m&in string 

Returns: ST.W - Position 

Registers used: All registers ecre preserved. 

Comperes the substring with the main string until a match is 
found. If no match is found, is returned. 

^•_CCPY - Copy a substring 

Peremeters: ST.L - Source string address 
ST.W - Starting index 
ST.W - Size to copy 
ST.L - Address of result 

Returns: — 

Registers used: All registers are preserved. 

If the ntmber of bytes to copy is 0, or if the source string is 
longer than the number of bytes to copy, the result string has 
lenth. 

%_DEL - Delete a substring from a string 

Parerfteters: ST.L - Address of string 

ST.W - Position to start deleting 
ST.W - Nimber bytes to delete 

Returns: 

Registers used: DO, Dl, D2, D3^ PO, Al^ A2 

XJ.\^ - Insert one string in another 

Parameters: ST.L - Address of string to insert 
ST.L - Address of main string 
ST.W - Position in main string to insert 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 
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5. String Cooparison Routines: XS_EO, XSJ€^ *S_LE^ tSJGE^ XS_LT, tSJGT 

All the string comparison routines are performed one byte at a time. 

^_E0 - String equal 

%S_^€ - String not equal 

^IlE - String less than or equal 

%S_GE - String greater than or equal 

^_LT - String less than 

^_GT - String greater than 

Parameters: ST.L - Address of first string 
ST.L - Address of second string 

Returns: ST.B - Boolean result 

Registers used: All registers are preserved. 



6. Set Manipulation Routines: X^IKTER, X SlhC, XJUNION, XJ)1FF, tJDIFF, 

XJWNGE, XJOZ, XJSEnnQE, X_SETL£, X^SOEQ, 
XJSETIC 

The forr^at of a set on the stack iS: 



— — + high address 

15-0 I 

+ 

31 - 16 I 

... I 



last word] 

n Bytes I 
-»-- -^ low address 
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%_INTER - Set intersection: setl fiND set 2 

% Ur^IOr>l - Set union: setl Cf5 set2 

%S>lff - Set difference: setl fiND (NOT sct2) 

^J©irF - Reverse set difference: (NOT setl) AND set 2 

Parameters: ST.S - First set 
ST.S - Second set 

Returns: ST.S - Result set 

Registers used: fill registers aare preserved. 

A_SING - Singleton set 

Peoraneters: ST.W - Singleton value 

Returns: ST.S - Result set 

Registers used: All registers are preserved. 

^._RANGE - Set range 

Parameters: ST.W - Minimurn value 
ST.W - Maximum value 

Returns: ST.S - Result set 

Registers used: All registers are preserved. 

Returns the set representation of the values from minimum to 
rnaximurn. If minimum is greater than maximum, a null set is 
returned. 

^.ADJ - Set adjust 

Parameters: ST.S - Set 

ST.W - Desired size in bytes 

Returns: ST.S' - Adjusted set without size word 

Registers used: All registers are preserved. 

Changes the size of a set to the given size. If the set is larger 
than the desired size, the extra values are thrown out; if the set 
is smaller thari the desired size, extra fields are added and 
initialized to 0. 
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^♦_SETNE - Set inequality test 

^ISETEO - Set equeJity test 

^•_SETGE - Set inclusion test (returns true if set2 is the same as or 

included in setl) 
VSETLE - Set inclusion test (returns true if setl is the same as or 

included in set2) 

Psierfteters: ST.S - First set 
ST.S - Second set 

Returns: ST.W - Boolean Result 

Registers used: All registers are preserved. 



7. Hiscellaneous Routines: XJ3QTCPa^ \JQ(Tro^ XJIftLT 

%_GOTOXY - Move the cursor to a specified location 

Parameters: ST.W - X coordinate 
ST.W - Y coordinate 

Returns: — 

Registers used: DO, Dl, D2, D3, ftD, Al, A2 

^._GOTOXY sends the following escape sequence to the screen to move 
the cursor position: ESC 

Y-^32 
X-.-32 

Y values are between and 31; X values between and 79. If the 
coordinate given is outside these bounds, it is set equal to the 
boundry value. 

VGO"fO - Global GOTO code segment remover 

Parameters: ST.L - Pointer to the desired last-segment jump table 

Returns: — 

Registers used: ftO 

Jumps from a nested routine to the first-level process. 
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^..HALT - Halt 

If the process is resident, it goes to step 5 of the %_INIT 
routine. If not, it calls "terminate^process" with the value of 
event_ptr as nil. Control does not return after this call. 



8. Range Check Routines.- X_RCHCK^ X_SRD*; 

^•_RCHCK - Range check, to check the bounds of subrange type variables 

Parameters: ST.W - Value to check 
ST.W - Lower bound 
ST.W - Upper bound 

Returns: — 

Registers used: fill registers are preserved. 

Note that if the check fails, this routine causes the systerri 
exception 'SYS_VftHJE_0C6' to be signalled and the message 'VALLE 
RANGE ERROR' to be displayed before the process is forced to enter 
the debugger. If the process has not declared ari exception 
handler for this exception, the system default handler is entered 
after the debugger returns control. The systetri default h&ridler 
terminates the process. 

^_SRCrt< - String range check, to check a string index against its length 

Parameters: ST.B - Value to check: 0..255 
ST.W - Upper bound 

Returns: — 

Registers used: All registers are preserved. 

Note that if the check falls^ this routine causes the system 
exception 'SYS.VALUE.COB' to be signalled and the message 'ILLEGAL 
STRING INDEX' to be displayed before the process is forced to 
enter the debugger. If the process has not declared an exception 
handler for this exception, the system default handler is entered 
after the debugger returns control. The system default handler 
terminates the process. 
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9. He^ Routines: XJCA, XJIflRK, X_RELSE, XJCMAV, XJEflPRES 

XJ€M - The New procedure. Allocate memory in the Pascal heap. 

Peiemeters: ST.L - Address of pointer 

ST.W - Number of bytes needed 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

*^_NEW sets the address of the pointer to nil. 

%_NEW checks whether the heap has been initialized (whether a date 
segment has been allocated) via the boolean Heaplnited. If 
Heaplnited is false, a call is made to the GrowHeap function to 
create and initialize a 'new heap'. If GrowHeap is unsuccessful 
(returns false) then %J€M is exited with the pointer set to nil. 

The GrovJHeap function initializes a 'new heap' by calling the 
PLInitHeap procedure. Growheap passes PLInitHeap the size of 
the Pascal heap data segement, the memory size (HeapOelta) and 
the logical data segment nonber (LDSN = 5). PLInitHeap then 
creates a private data segment with the pathname PascalLHeap, 
and assigns the segment pointer address to the pointers 
HeapStert and HeapPtr. PLInitHeap sets the pointer HeapEnd to 
point to the end of the segment (HeapStart •► segment size - 
256). 

Before assigning an address to the pointer, %_NEW determines 
whether there is enough room on the heap (i.eT in the data 
segment) for the variable. %_NEW makes a second call to the 
GrowHeap function. If GrowHeap is unsuccessful, then X^NEW is 
exited with the pointer set to nil. 

The GrowHeap function calls the GetSafeArrmount procedure to 
determine the maximtm ntinber of bytes by which the heap can be 
increased (the amount of system memory available to the calling 
process). If this amount is greater than the current size of 
the heap, then Gro^eap will double the size of the heap, 
otherwise GrowHeap will increase the heap to the maximum amount 
available. The pointer HeapEnd is incremented by the amount of 
increase. 

%.NEW then sets the address of the pointer to the address of 
HeapPtr, which points to the next free area on the heap. The 
address of HeapPtr is increased by the size of the variable that 
was placed on the heap. 



27'January^e4 Pf^LJ&-J2 



Internals # Confident: 5. 



^_MARK - The Mark procedure. Mark the Pascal heap. 

Paremeters: ST.L - Address of pointer to be marked 
ST.W - Nuftber of bytes needed 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, ftl, A2 

X_MARK checks whether the heap has been initialized via the 
boolean Heaplnited. If Heaplnited is false, a call is made to the 
GrowHeap function to create and initialize a 'new heap'. If the 
function is unsuccessful (returns false) then %_MfiRK is exited. 

The GrowHeap function is described under %_ICW, above. 

^_MARK sets the address of the pointer to the address of HeapPtr, 
which points to the next free area on the heap. 

^•_RELSE - The Release procedure. Release the Pascal heap. 

Parameters: ST.L - Address of pointer to release to. 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, ft2 

%_RELSE checks whether the heap has been initialized via the 
boolean Heaplnited. If Heaplnited is fal^. e call is made to the 
QrowHeap function to create and Initialize a 'new heap'. If 
GrowHeap is unsuccessful (returns false) then ^._RELSE is exited. 

The GrowHeap function is described under %_fCW, above. 

If the pointer does not point within the heap (i.e., address 
memory between HeapStart and HeapEnd), an error will result and 
the procedure will be exited. 

If the pointer is less than HeapEnd minus HeapDelta, (where 
HeapDelta is the original size of the heap) the heap is reduced in 
size by HeapDelta. 

%_RELSE sets HeapPtr (which points to the next free area on the 
heap) to the address of the pointer. 
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%__MEMRV - The Memff^ail function. Memory Available in the Pascal heap. 

Paiameters: None. 

Returns: — 

Registers used: fill registers are preserved. 

^.^MEMftV generates a call to the %_PHWordsftvail function, which 
determines the amount of words available. 

%_PHWordsftv/ail checks whether the heap has been initialized via 
the boolean Heaplnitcd. If Heaplnited is false, a call is made to 
the GrowHeap function to create and initialize a 'new heap'. If 
GrowHeap is unsuccessful (returns false) then %_PHW or ds Avail is 
exited. 

The GrowHeap function is described under %_hEW, above. 

%_PHWordsftvail determines the maximixn nanber of words available 
(the amount left in the heap data segnent minus the maximum amount 
of system memory awai labia) and the current nciriber of LDSr>l words 
available (the maximun nimber of words you can get by the chosen 
LDSN minus the number of words already used). If the maximum 
number of words available is greater than the current ntmber of 
LDSN words available, then the current nimber of LDSN words 
available is returned, otherwise the maximun number of words 
available is returned. 

%_HEfiPRES - The HeapResult function. 

Parameters: ST.W - Heap result 

Returns: — 

Registers used: All registers are preserved. 

Refer to the hfarkshop User's Gificfe for the values of the heap 
result . 

^_HEAPRES generates a call to the %J*HeajdRes function. V^hHeapRes 
is assigned the integer value of hCrrResult. 
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10. Read and Itrite Routines: X_KEYPRESS, *W_LH, W_C, W_STR, W_PAOC, W^^I, 

W B, X P«3E, »_C, »J. « Srm, V^PPCC, 
«_LW, X_EDLN 

fill the read and write routines take 'file address' as a parameter, which 
Is the address of the file variable. The address of the Pascal standeard 
Input is in offset 8 from register ft5; the address of output is in offset 
12 from A5. 

X^KEYPRESS - The Keypress function. 

Par erne ters: ST.L - File address 

Returns: ST.B - Boolean Result 

Registers used-. All registers are preserved. 

Note that the file address is not used in the current implementa- 
tion. 

^_KEYPRESS generates a call to the %_PKeyPress function and 
returns the result of %_PKeyP'ress as~its result. 

The %_PKeyPr ess function determines whether any keys heve been 
pressed. It returns true if the look-ahead buffer is full, 
otherwise it returns false. 

%W.LN - WriteLn 

Parerneters: ST.L - Address of output file 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

W^LN calls the FWriteln procedure, passing it the address of the 
file. FWriteln calls the FWriteChar procedure, passing it an 
PSill <CR> (end-of-line) to be appended to the string. 
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%W_C - WiiteCheo:. Display a character on the console. 

Parameters: ST.L - Address of output file 
ST.B - Character to be output 
ST.Vf - Size of field to print 

Returns: - — 

Registers used: DO, Dl^ D2, D3, ftO, ftl, A2 

*4fiS calls the ?^WriteChar and OutCh procedures to write a 

character to the file. 5jW_C passes DotCh the character to be 

written and the address of""the output file. OutCh then calls 
FVJriteChar to write the character to the file. 

The default field size is 1. If the field size is greater than 1, 
%fiS calls FWriteChar to write out the appropriate nunber of 
spaces, then calls OutCh, which calls FWriteChar to write the 
character. 



W_STR - Write string 

Parameters: ST.L - Address of output file 
ST.L - Address of string 
ST.W - Size of field to print 

Returns: — 

Registers used: DO, Dl, 02, 03, AO, Al, A2 

If the string size is greater than 255 characters, then W.STR 
truncates it to 255. 

%w_STR then compares the field size (Minwidth) to the specified 
string size. If the field size is less than or equal to zero, 
it's set to the string size. If the field size is less than the 
string size (but greater than zero)^ then the string size is set 
to the field size. If the field size is greater than the string 
size, then a call is made to the FWriteChar procedure to write out 
[MihWidth minus string size] spaces. 

%W_STR then calls FWriteChar to write out the string with the 
specified string size. 
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W_PACC - Write a packed array of characters 

Parameters: ST.L - ftdcJress of output file 
ST.L - Address of string 
ST.W - Actual length 
ST.W - Size of field to print 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

The effect of W.PAOC is the safne as calling %W_STR with the 
specif ed field size equal to the number of elements in the arrs^/. 

^_I - Write an integer 

Parameters: ST.L - Address of output file 
ST.L - Value to print 
ST.W - Size of field 

Returns: - — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

%A_l compares the field size (MinWidth) to the size of the 
integer. If the field size is greater than the size of the 
integer, then %AJL calls the FWriteChar procedure to write out 
[MinWidth minus integer size] spaces. 

%W_I then calls fWriteChar to write out the integer with the 
specified integer size. 
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'm^ - Write a boolean 

Perameters: ST.L - Address of output file 
ST.B - Value to print 
ST.W - Size of field 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, ftl, A2 

^_B calls the ^_STR procedure, passing it the string to be 
written, the size of the string, and the address of the output 
file. 

If 'value to print' is zero, %A_B passes the string 'FALSE' to 
^_STR, with a string size of 5. 

If 'value to print' is 1, ^_B passes the string 'TRUE' to W_STR, 
with a string size of 4. 

^_STR then writes the string to the output file. 

^_PAGE - Page procedure 

Parameters: ST.L - Address of output file 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

^•_PAGE writes the ASCII character TF' to the output file by 
calling the OutChar procedure. OutChar is passed the character to 
be written (e.g. '^?') and the address of the output file. 
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yf^S- ' ReadChao: 

Parameters: ST.L - File Address 

Returns: ST.B - the character read 

Registers used: DO, Dl, D2, D3, 90, ftl, A2 

^_C reads a character from the specified file by calling the InCh 
function, then returns the character on the stack. 

Ir£h calls the FResdChar function, passing it the file address. 

FRcacChar verifies that the file has been opened, calls the 
FGet procedure, reads the character that is placed in the 
window buffer area by FGet, arid passes the character back to 
InCh. 

ttf5_LN - ReadLn 

Parameters: ST.L - Address of input file 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

^^LN reads a line frorn the specified file by calling the FReadLn 
procedure, passing it the file address. 

FReadLn verifies that the file has been opened and then calls 
the FGet procdure to read each character on the line until EOLN 
is true. When EOLN is true, FReadLn resets EDLM to false and 
returns to !5R_LN. 

^,PAOC - Read Packed Array of Character 

Parameters: ST.L - File Address 
ST.L - Array Address 
ST.W - Size of array in bytes 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

The effect is the seme es calling ^_STR whose specified field is 
the number of elements in the array. 
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%R_STR - Read String 

Parameters: ST.L - File Address 
ST.L - String Address 
ST.W - Max size of string 

Returns: — 

Registers used: DO, Dl, D2, D3, AO^ ftl, A2 

^_STR first verifies that EOLN is false, otherwise ^_STR returns 
to the calling routine. 

^_STR then generates a loop which reads a character from the file 
by calling the InCh procedure (described under *^S, abCN/e), then 
checks whether EOLN is true. If EOLN is true, ^tfTsTR rettjrns to 
the calling routine. If EOLN is false, 5tf?_STR reads the character 
and returns to the beginning of the loop to read the next 
character. 

After InCh returns a character, 5JR STR checks whether the 
character is a RLBOUT (ASCII 'OLE' J or BACKSPACE (ASCII 'K'). If 
the character is either of the two, ^_STR processes the character 
accordingly and then reads the next character. If the character, 
is not RUBOLTT or BACKSPACE, the character is read and ^_STR 
leturns to the beginning of the loop to read the next character. 

^_1 - Read Integer 

Parameters: ST.L - File Address 

Returns: ST.B - The integer read 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

^.I consists of two main loops which reads characters from the 
file to form a valid representation of an integer value. 

The first loop reeds a character from the file by calling the InCh 
procedure (described under W_C, above). If this character is 
<CR> or space, ^_I returns to the beginning of the loop to read 
the next character. If the character is not <CR> or space, 5iR_i 
exits the first loop. 

Next, t5R_I determines whether the character read is a sign 
character ('-f' or *-'). If it is, ^JL enters the second loop and 
calls InCh to read the next character" If the character is not a 
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sign chsjacter, %R I enters the second loop bv,'passing the call to 
InCh. 

The character is then checked to see if it's a RLBOUT or BftCXSP(^£ 
,. character; if it is, the character is processed accordingly and 
^_I returns to the beginning of the first loop. 

The character is checked once more to determine if it is a valid 
integer value (0 < character i 9). If it is, ^_I returns to the 
beginning of the second loop and calls InCh to read the next 
character. 

If the character is not a valid integer, then 5tf?_i checks to see 
if any characters read previously have been valid integers (by 
checking register D6). If no characters have been valid integers 
(D6 = 0), then ttf5_I generates ari lOResult error. If the characters 
reed previously have been valid integers (D6 =1), then *^J1 
returns to the calling routine with an integer result. 

V^OLN - End of line predicate 

Parameters: ST.L - File address 

Returns: ST.B - Boolean Result 

Registers used: All registers are preserved. 

%_EOLN returns true if the end of a line has been reached in the 
specified file. 
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11. File I/t) Routines: X^REWRT, %^RE5ET, XJCIDSE, XJEDF, X^BLKRD, X^BUOi^, 

*_IGRES, %_GET, X_PUT, XJUPfiRR, X^SEEX 

^•_REWRT - Rewrite a file 

Parameters: ST.L - File Address 

ST.L - Address of Name String 

ST.W - Kind: -2=text, -l*file^ >0=nurftber of words per 
record 

Returns; — 

Registers used: DO, Dl, D2, D3, AO, ftl, A2 

Creates and opens a new file. 

^RE^T first initializes the file's FIB (file identification 
block) by making a call to FInit and parsing it the file type via 
the parameter recOytes. Once the file type is determined^ the 
value of FRecSize is initialized. The values of recBytes and 
FRecSize and the file types are: 



recBvtes 
-2 
-1 




file type 

text 

untyped 

interactive 

typed 



FRecSize 
-1 

-1 
value in recB^'tes 



Other important FIB entries are initialized as follows: 



FIsOpen 
FNewFile 

FEOF 
FEOLN 
FModified 
FIsOS 



false . - The file is marked as not open 

false . . The file is marked as not new 

(i.e. no creation of new files) 

true . . End Of File is set to true 

true . . End Of Line is set to true 

false . . The file is marked as not modified 

true . . The file is marked as an OS File 



t5_REVff5T then calls FOpen. Within FOpen: 

A check is made to determine whether the file has been opened 
by referencing the boolean FIsOpen. If FIsOpen is true, an 
lOResult error will occur; if not^ it is set to true. 

FOpen then determines whether the filename is one of the 
character devices CH^BOLE, KEYBOARD, or PRirfTER. If it is, 
FOpen opens the file. If the filename is PRINTER, a check is 
made to determine if the printer is connected. If the printer 
is not connected, an lOResult error will be generated. The FIB 
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variable FUnit is also set accordingly: l«CONSOLE, 2=KE:YB0fiRD, 
3«PRINTER, 10=other dev./ices (not pseucio de-v/ices). \ 

The FIB variable FNewFilc is set to true to indicate that a nev 
file is being created with a rewrite, otherwise its value would 
remain faJse indicating a reset operation. 

FOpcn creates and opens a new ternporary file if the filename 
does not exist (i.e. if FNewFile is true), otherwise it opens 
the existing file. If the temporary file is of type TEXT, 
FOpen writes two header blocks of null to the file. FOpen also 
kills the temporary file so that it may be unkilled during the 
close. 

^_RESET - Reset a file 

Parameters: ST.L - File Address 

ST.L ~ Address of Name String 

ST.W - Kind: -2=text, -Isfile, >0=nurf.ber of words per 
rccord 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, ftl, ft2 

Opens an existing File. 

\RESET behaves in the same manner as %_REV*?T, by making calls to 
procedures FInit and FOpen. However, %JrESET does not create a 
temporary file (FNewFile is false). It~attcmpts to open the 
existing file and if it is unsuccessful will issue an lOResult 
error. 

Before exiting FOpen, %_RESET makes a call to the FReset procedure 
which in turn cells the"FGet procedure. This has the effect of 
advancing the file position to the first record of the file. 
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%^CLOSE - Close a file 

Parerneters: ST.L - File Address 

ST.W-Mode: 0=rCRMAL, 1«L0CK, 2=PURGE, 3»CRUNCH 

Returns: — - 

Registers used: DO, Dl, D2, D3, ftO, Al, A2 

If the file is a character device (e.g. console, keyboard) or if 
the file is not open (FlsOpen is false), the close procedure has 
no effect. 

CRUNCH and LXK Options-. 

If the close option is either CRLICH or LOCK, arid the file is a 
text file that had been opened by RESET (FNewFile is false), a 
check will be made to determine if the nimber of blocks is odd. 
If it is, a null block will be written to the end of the file. 

If a previously existing file was opened by REVff^ITE (FNewFile 
is true), it will be killed (i.e. deleted). Its temporary 
file., which was killed by FOpen, is unkilled using the original 
file name as the new file name. 

PURGE Option: 

If the file was created by REWRITE, the temporary file will 
have already been killed in FOpen. 

The PURGE option will kill the original file provided it was 
opened by RESET (R«lewFile is false). 

NORMAL Option: 

If the file was created by REWRITE, the temporary file will 
have already been killed in FOpen. 

The original file is left untouched. 
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X_EOF - End of file predicate 

Parameters: ST.L - File address 

Returns: ST.B - Boolean Result 

Registers used: All registers are preserved. 

Detects the end of a file by referencing the FIB boolean entry, 
FEOF. 

VBLKRD - Blockread 

Parameters: ST.L - File Address 
ST.L - Buffer address 
ST.W - Number of blocks to reed 
ST.W - Block Number, -1 « Sequential 
*♦♦♦*♦ ST.W - DoRead, « write, 1 « read **♦♦♦ 

Returns: ST.W - Number of blocks actually read 

Registers used: DO, Dl, D2^ D3, 9C, Al, ft2 

^_BLKRD generates a call to the FBlocklO function, passing the 
parameters listed above. The boolean variable DoRead is set to 
true for Blockread and false for Blockwrite. 

Within FBlocklO: 

If the file is not open (FIsOpen«false) and the number of 
blocks to transfer is less than zero, FBlocklO will generate ari 
lOResult error and the file will not be processed. 

If the file is the character device CONSOLE or KEYBOARD, an 
lOResult error will be generated and the file will not be 
processed. 

If the file is the character device PRINTER, the block number 
to start the transfer (RBLXCK) Is set to -1. 

If the boolean DoRead is true, FBlocklO reads blocks ftom the 
file via a READ DATA call^ otherwise FBlocklO writes blocks to 
the file via a WRITE.DATA call. 

Before these OS calls can be made^ the node and offset must be 
determined. 
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IT the block number to start the transfer (RBLOCK) is less than 
zero, the mode is SEOUE^mAL and the offset is zero^ otherwise 
the mode is ABSOLUTE and the offset is calculated as: 

ord4(rblock) ♦ FBlkSize 

Mhere FBlkSize is the Standard Disk Block Length (512) 

The nunber of blocks actually read or transferred is calculated 
as: 

FBlocklO :* actual div FBlkSize 

where 'actual' is the nimber of bytes transferred by the 
READ^DATA or WRITE.DATA OS calls. 

EOF (FEOF) is set to true when the last block is read. 

^.BLKWR - Blockv^ite 

Parameters: ST.L - File Address 
ST.L - Buffer address 
ST.W - Nimber of blocks to write 
ST.W - Block Number, -1 « Sequential 
*♦♦♦*♦ ST.W-DoRead, « write, 1 « read ♦♦♦♦♦ 

Returns: ST.W - Number of Blocks actually written 

\.BLKWR behawes in the same manner as \.BLKRD, except it passes 
the boolean variable DoRead with a value of false when calling 
FBlocklO. 



XJOPES - lOResult 

Parameters: None 

Returns: ST.W - lORcsult 

Registers used: All registers are preserved. 

Refer to the ii/orkshop User's Gui^^ for the values of lORcsult. 

Returns an integer value that reflects the status of the last 
completed I/O operation. Note that the code indicates 
successful completions, positive codes indicate errors, and 
negative codes tut warnings. 
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^•_I0RE5 makes a call to function FIOResult, which in turns 
references the variable lORslt. The variable lORslt is assigned 
values by the procedure %_SETICIRSLT. This procedure is called b^; 
FPLib and appastext only. 

^JGET - Read the next record in a file 
Peran^eters: ST.L - file Address 
Returns: — 

Registers used: DO, D1/D2, D3, AO, Al, ft2 

^_pUT - Write the current record in a file 

Parameters: ST.L - File Address 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

If %PJ\ is called immediately after a file is opened with 
^•_RE&T, the PUT will write the second record of the file (since 
the %_RESET sets the current position to the first record and 
^♦_PUT"'advances the position before writing). 

^_UF'ARR - Compute the address of F" 

Parameters: ST.L - Address of file 

Returns: ST.L - Address of F* 

Registers used: All registers are preserved. 
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%_SEEK - Allows access to an arbitrary record in a file. 

Paranieters: ST.L - Address of file 

ST.W - Record number to seek 

Returns: — 

Registers used: DO, Dl, D2, D3, AO, Al, A2 

If the record nimber specified does not exists, 

1) ^_SEEK causes the next GET to access the last record in the 
last block of the file. 

2) %_SEEK causes the next PUT to append the record to the end 
of the file. 
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PPaslibC Unit: 
Privileged PASLIB Calls 



The unit PPaslibC provides you with several useful low-level system functions. 
However, the^' ate not for e^-'eryonef They ere tricky, in some cases heve global 
effects on the entire system, and should be used with caution. 

In order to use these routines, you must use the units SYSCALL and PPaslibC: 

($U SysCall) SYSCALU 
{$U PPa&libC) PA5LIBCALL; 

This gives you access to the routines listed below. These routines ere contained in 
lOSPASLIB.OBJ, so programs using them require no additional inputs to the Linker. 

procedure BlocklOinit; 

Initializes all shared PASLIB data. Opens inputfile and output file, 
associating thenri with the filename -CONSOLE. 

BlocklDlnlt must be called by every shell before performing any I/D; it 
will only be executed by the first shell that calls it. 

It is called b^/ the system. shell at boot time, once for the entire systerr.. 

procedure BlocklOdisinit; 

PASLIB cleanup. BlocklOdisinit closes the console only for the first shell 
that called the BlocklOinit procedure. 

procedure Locl^aslib (veor errntm: integer); 

where: 

errnn is the error number returned if the procedure has any problems. 
(See Appendix A of the Workshop User's Guide for an 
explanation of the error codes.) 

Locks the PASLIB 1 segment in memory so it won't be swapped out. Used by 
the filer for unmounting the boot device. 

procedure LocW^asIOlib (vor errnuD: integer); 

where: 

I' ermin , is the error nunber returned if the procedure has any problems. 

Locks the PASIOLIB segment in memory so it won't be swapped out. Used by 
the filer for unmounting the boot device. 
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procedure tioveConsole (vsr CErrniA): integer; appl console: consoledest); 

where: 

errnui is the error nimber returned if the procedure has any problerrr:. 

applconsole tells where to move the console. (Consoledest is an 

enumerated type of: alscreen^ mainscreen^ xsorocA^ xsorocB, 
folder, spare 1, spare2, spare3.) 

Moves the console to the main screen^ an alternate screen, or an external 
terminal connected through RS232A or RS232B. The file names are: 

Alternate Screen -ALTDDNSOIJE-X 

Main Screen -hftINC0N5OL£-X 

External RS232A Terminal RS232f^X 

External RS232B Terminal RS232B-X 

procedure ExecReset (var errnum: integer; execfile: pathname; stopexec: 
boolean); 

where: 

errnui is the error number returned if the procedure has any problems. 

execfile is the exec file name. 

stopexec tells whether to open or stop the exec file. 
TRIE a stop; FALSE - open. 

If stopexec is TRUE, ExecReset closes the input file and 
reopens it, associating it with the temporary exec file. It 
then generates two calls to the FReadchaor function to read and 
save the temporary file's first character into the variable 
gfirstchar, and the next character into greadahead. ExecReset 
then sets the boolean gexecflag to TRLE. 

If stopexec is FALSE, ExecReset calls the Resetinput procedure, 
which closes and reopens the input file, associating it with 
-CONSOLE. ExacReset then sets the boolean gexecflag to FALSE. 

Opens or stops an exec file. 

ExecReset is called once by the Exec Command Interpreter, to open and read 
from the exec temporary file and reopen the input file to the console. 

function ExecFlag: boolear^ 

Tells whether an exec file is open. TRUE « open; FALSE « closed. 
ExecFlag references the input file FIB boolean entry FSOTTBUr. 
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procedure Out putRedlrect (vsr eimun: integer; outfile: pathnone; stopoutput: 
boolean); 

where: 

errnui is the error nimber returned if the procedure hes any problems. 

oi/tfile is the file name. 

stopoutput tells whether to close the file or leave it open. 
TRIE « close; FALSE « leave open. 

If stopoutput is TRUE^ CkitputRedixect calls the Reset output 

procedure, which closes and reopens the output file, 
associating it with -CONSOLE. 

If stopoutput is FALSE, OutputRedirect closes the output file 
and reopens it, associati?ig it with the filenarrte outfile. 

Redirects output to a file. 

function OutputRFlag: boolean; 

Tells whether output hes been redirected to a file. TRUE = output file 
open (output redirected); FALSE • closed (output not redirected). 

OutputRTlag references the output file FIB boolean entry FSOnBUF. 

procedure DSPaslibCall (var PtocParan: dsProcPasraM); 

where: 

dsProcPoran « record 

case ProcCode : dsProcCode of 
dsResProg : (RProcessld : longint); {sust be called 

before the process starts running.} 
dsSoftP^tn : fSPButton : boolean); {result} 
dsPrintDcv : iPiOcvicc : e^rwit e); 
dsSetGPrefix : (errniii : IKTEGER; {result} 

prefix : pothnetDe); 
dsEnbDisk : (DiskEvent : boolean); 
dsCiTranlisaCar : (toTranslate : boolean); 

{to turn on or off translation for C. Itoh} 
and; 

dsProcCode « (dsResProa dsSoftf\*tn, dsRrintOev^ dsSetGPrefix^ 
dsEnfaOisk^ dsCiTranlisaCar); 

dsResProg passes the process ID of a process that is going to be 
resident to PASLIB. 

dsSoftPwbtn returns the soft power button setting. If the button is 
pressed, it returns TRUE; if not, it returns FALSE. 
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dSPrintdev passes the pfrysical device none of the corresponding 
logical device -ffUhfTER to Ph6LIB. 

dsSctGPrefix passes the global prefix volune name to PftSLIB. If an 
error has occijrred^ it is returned in erxnui. 

dsEnbDisk tells PASLIB to enable (if DiskEvcnt is TRIE) or disable 
(if OiskEvent is FALSE) the automatic mounting and 
ejecting of a diskette. 

dsCoTranlisaCax tells PftSLIB to turn on (if toTranslate is TRUE) or off 
(if toTranslate is FALSE) the Lisa character trarislation 
for a C. Itoh printer for the calling process. The 
default setting is on. 

DSPaslibCall is a new call in the PPaslibC unit that communicates to and 
from PASLIB about the run-time support for the system or the calling 
process. It has a variant-record parameter for indicating various 
functions. Note that most of these functions dictate system behavior; they 
are not safe for any process to call except the Lisa character translation 
function. 
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Eiecutioii Environment of the Lisa Ptea] Cbmpller 


Registers: 




D0-D2/AD-A1 


User lemporaries 


DO-EQ/AO-Al 


Cbmpller temporaries 


D4-D7/A3-A4 


OompHer uses for locals & pointers 


AS 


Pointer lo gbbal ftame 


A6 


Pointer lo local firame 


A7 

Global Frame: 


Pointer lo top of siack 



The global fhtme consists of two segments: 

1} The Jump Table Segment 

2^ The Stack Segment (first of N segments) 
The global £rame is layed out as follows: 





Jump Table 




Segment Table 




Data Pointer Table 




Shared Main Ptegram Parameters 


Private Main Program Parameters 


Main Program Globals 




Regular Unit Globals 




Intrinsic Unit Globals 


A6-^ 


Dynamic Iters Stack 
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The Jump Table is a an array of 6 byte JMPs used to 
transfer control between segments of the program and 
the regular units used by the program. This is built by 
the Linker from Entry points and Externals reference lists. 

The Segment Table is a structure which defines each of 
the segments of the program and the regular uniti This 
is used by the Loader to swap in segments. For each of 
the segments^ the Segment Table prodddes a Hie address^ 
size of code (pacted & unpadted sizes) and the logical 
^dress (ie. segment number). 

The Data Pointer Table is an array of 4 byte pointers 
which is used to reference global data fbr intrinsic units. 
This structure is built by the Loader and referenced by 
compiled code. 

. The Shared Main Program Parameters is an area reserved 
ihr use by the Loader to store infbrmation about the main 
, pfograoL Currently this area is SlOO bytes. . 

The Private Main Program Parameters is an area initialized 
bf the loader and referenced by compiled code* This area 
contains pointers to INPUT and OUTPUT file buffers and 
other infbrmation such as the size of the regular unit globali 
Ctoently this area is $100 bytes. 

The Main Program Globals is the global data allocated by 
tte compiler fbr the program. 

The Regular Unit Globals is the combination of all global 
data required by the regular units used by the program. 

The Intrinsic Unit Globals is the private global data which 
is required by the intrinsic units used by the prc^ram. 

The Users [)ynamic Stack is that area which is used by the 

pfo^ram fbr local frames, temporary data and procedure 
linkages (both pascal and assembly language). 

Initially the Loader allocates enough space to cover these 
areas and the user min stack requirements. The system also 
' enfbrces a upper limit (ie. max stack). 
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Local Frame: 



The local frame consists of the Mowing: 

1) Function result and parameters 

2) Static and dynamic Ms 

3) Locals and compiler temporaries 
4} Dynamic stad: area 

The local frame is lajed out as fbllows: 



A6 



Function Result 



Parameters •• 



Static Link 



ttt 



Return Address 



PTnamicdLinlr 



Locals 



Compiler Temps 



Dynamic Stack Area 



^ Two or fbur byte f\mction result, present only for functions. 

^ N bytes depending on the parameter list 

^ Present only fbr non level 1 ^xtedures and parameters^ 

The local fiame is allocated by the compiler and allows the 
compiled code to reference locals, paramiers, static linb, - 

The dynamic M 0e. 01dA6) is pushed by the LINK A6 
instrudon which allocates space fi3r locals and compiler tempi 

the static M is pushed by the caller as pan of the parameter 
list The static M is a copy the parents A6 (ie. local frame). 

Cfampiler temporaries are used to implement constructs such 
as non local gotos and expressions computed by the compiler 
which happen to not be in registers. These expressions may 
include fbr loop limits or with expressions. 

Parametric procedures and functions appear as fbUiows: 



Address of proc/func body 



Zero or static link 



Note zero is used fior level 1 procedures. 
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Automatic Stact Expansion: 

The compiler communicates the space requirements for each 
procedure by preceding each LINK A6,#-5i2e with one of the 
following sequencer. 

TST.W c(A7) 

MDVEL A7,A0 
SUEL /size^Q 
TST.W (AO) 

The offset U9ed inthefirstcasearthesizeinthe second reflect 
the sum of the procedures static and dynamic requirements. 
This sum Is inflated by at least $100 bytes to allow assembly 
bnguage procedures to use a small amount of stack space at 
low cost (ie. they need not check). Note the code for automatic 
stack expansion can be controlled with a compile option. 

JSRs, JMPs. LEAs and PEAs; 

These instructions are used to transfer control and obtain the 
address of a procedure or function. These instructions exist in 
three ifarms all of which occupy 4 bytes each: 

I) Within a segment PC relative 

^ References to regular segments: Ofl^sets from A5 

3) References to intrinsic segments: lU Trap instructions 

The first form is simply a refisrence to a procedure from within 
the same segment which uses the PC relative addressing mode. 

The second fbrm is a reference to a procedure which is not in 
the same segment but is contained in a segment of the prc^ram 
ora regular unit This is implemented by using an offset from 
AS to reference the procedure through the Jump Table* 

The third fbrm is a reference to a procedure which is contained 
in an intrinsic segment (ie. in an intrinsic unit). This fbrm is 
implemented by using Line 1010 trap mechanism to compress 
the opcode and 24 bit logical address into a 4 byte instruction. 

In eadi of the above cases the compiler emits references the 
desired procedure or function and the linker constrcuts the 
apptopiate addressing mode fbrJSRs, JMPs, LEAs and PEAs. 
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Structure of Code te a Pascal Procedure or Function: 

The code emitted by the compiler contains three constructs which 
can be controlled via compile time options. These are as follows: 

1} Automatic stack expansion. 

2) Range checking for values, indexes and strings. 

3) Debuggung info (le. the procedure name). 

The code for a typical procedure wOllook as follows: 



TST.W 



e(A7) 
A$,#-size 



Tests for suiBdent stack space 
Allocates space for locals 



body of the procedure or function 



UNLK 
RTS 



A6 Restores previous local frame 

Exiisequence 

Bghi byte procedure name and 
vm bytt data size. This is the 
optiooal debugging inibrmation. 



constant data area for strings & sets 

The exiisequence emitted by the compiler is dependent on the 
number of bytes of parameter! If there are no parameters then 
the RTS is used as shown above. The compiler emits one of the 
following sequences when parameters must be deleted: 






Ome #1: Z 6 Of 8 bytts of paiamieg 

MOVEL (AT)-!-^ 
ADDQ.W #size^7 
JMP (AO) 

Case jf 2: 4 byies of parameiefs 

MOVE! (A7)+^A7) 
RTS 

Case #3; more than 8 bytes of parameters 

MOVEL (A7)+^0 
ADD.W #sia^7 

JMP (AO) 



2 
2 
2 

Tbytes total 

2 
2 

T" bytes total 

2 
4 
2 

Tbytes total 
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Segmentation & Large constants passed by value: 

Since the 68000 is not restamble» (le. use a 68010 instead) the 
data (ie. stack and heaps) fbr a ^n program must be present 
while the program is executing. Since code segments must be 
swapped into memory as needed and set and string constants 
are stored with the code, large constants passed by value pose 
ft problem. Currently, we solve this problem by having the 
compiler use the ins^uction TST3 (Ai) to check to see if the 
the actual value parameter is in naemory. If the TST£ (Ai) 
causes a fkult then the system k»ds the segment containing the 
address in AL 

When copying strings the compiler emits code which depends 
only oa the size of the destination. This may cause the code 
to read beyond the end of a segment The system allows fbr 
this by mapping code segments to cover size -h 256 bytes. The 
heap segments also have an additional 256 bytes. 



4^Ma^83 Compiler Execution Emrironment-e 



Shell-Writer's Guide 



This document contains information you need to know to v^Tite a shell for the Lit&. 
]t describes the things a shell must do when it starts up and when it terminates. To 
use this document, you should be farriiliar with the Operating S^^stem Reference 
Manual and hef^e some knowledge of Pascal. To do any graphics, you will hev^e to 
use QuickDraw, described in the Pascal Reference hiariual. You ma^' also want to use 
calls in the PaslibCall and PPasUbC units. 

The 9y«tam.thcll 

When the OS is booted, it starts the 'root' process, which searches the boot disk for & 
shell called 'lyxtem.sheir. The tyitem.thell is automatically started, and will be the 
ancestor of all other shell processes (see Figure 1). All shells must be "plug- 
competible" with each other so that any shell can be the iyitem.jhell without speci&l 
support from the OS. In this wa>', a turn-key boot disk could be prepared that didn't 
include a selector shell. 




^ Workshop J / [ Office Syitem ] \ f 



other shells 



) 



OS shell 
MtraOos) 



[ 



still more 
Shells 



Figure 1 
Process Picture 
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If your shell u the first process (the iyxtem.thellX you must make the following 
system initialization calls. Normally, the selector shell takes care of this for you. 

Startup: procedire BIockDInit; Initializes Pascal I/O. (Note: if you don't herve 

the privileged PASLIB interface^ declare BIockDInit external.) 

procedire PMinit (var error: integer); Initializes parameter miemory. 
(Note: you have to be able to link against the pmm unit to 
make this call.) 

function enableDbg (on: boolean): boolean; Activates LisaBug if you 
want to use it. 

irocedire tetNMIkey (ke^^ap: integer]; Makes LisaBug accessible 
through the NMl key. 

Tern-iination: proceckfe BlockIX)iiInit; PASLIB cleanup. (Note.- if you don't have 

the privileged PASLIB interface^ declare BlocklOInit external.) 

To tell if yo'jr shell is the «yjtem.thcll, call: 

inf ojrocen (OSErr^ MyJd^ Rnfo) 

If Plnfo.father_id is 1 (the root process), then you're in the «yttem.jhell. 

The EfTv'ironments window is the sta/^derd syfterathell It scans the directory of the 
startup disk for files whose names begin with 'ihell.'. For your shell to be recognized 
and a^'ailable from the En-v'ironments window, the narrie of its object file must start 
with 'shell;. 

Interproce» Communicalion 

Event channels are used for communication between processes. The root process and 
the selector shell expect information from their son processes through a 
SYS_SONI_TERM e^/ent channel, telling why the son terminated, and whether the father 
should restart the son, select or start another shell, turn the power off, or restart the 
machine. The OS guarantees that this event will always be sent back to the father of 
a terminated process via the local event channel^ even if the son process was 
unwillingly aborted. 

At Shell Startup 

FATHER: A process that starts a shell must do the following: 

1) Establish a local event channel to allow its son to communicate with it 
(OPEN.EVENT.CHM). 

2) Start the son shell (MAKE.PRDCES?). 

3) Wait for a SYS_SON„TERM event (WMT^EVENT^CHNf). 
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SON: The shell thst was tteited mujt do the following: 

i) Declare a SYS^TERMINATE exception haridler (DECLARE.EXCEP^HDL). 

This exception will be signalled when the shell process is at'out to be 
terminated for any reason: because KILL_PROCESS or TERMINATE_PFDCESS 
has been called; because the process rari to connpletion; t»ecau$e there has 
been a bus error, address cnor, illegal instruction, privilege violation, or line 
1010 c«r 1111 emulator error. 

If this procedure is declared, the OS will always give it a chance to run 
before the process is terminated. 

It is recommended that new thells not assume anything about the state of the 
machine (e.g. the console setting, etc.). 

For more information on r-.^ent channels arid on starting up other proceises from a 
$hell, refer to the Operating fystem Reference Manual 

At Shell Tcsmination 

SON: It is the shell's responsibility to make the operating system call to 
TERMINATE.. PFDCESS to open an event channel, »_evcntblk (an array of longints). 
The first entry of this block (s.eveniblk[l] ) containrthe event that tells the sheilas 
father what to do. The chosen meanings for these values aie: 

1— Restart same shell (shell crashed and needs to be restarted). To avoid infinite 
loops of START - CRASH - RESTART - CRASH..., the user will be at-le to 
intervene when the selector shell is reached. 

2— Select another shell (SELECT_ANDTHER command). 

3 — Start the specified shell. The remaining longints in the event text block 
(f_eventbU<[2-.9] ) are interpreted as a packed array [1..32] of characters (with 
no length field), containing the file name of the shell to be started. The 
unused portion of the array is packed with spaces. 

4— Turn miachine off (white power button clicked, or POWERJDFF command). 

5— Reboot the machine. 

C3ther — Unspecified. 

It will be the job of the shell's terminate exception handler (which is just a procedure 
the thcll owns) to guarantee that the proper SYSJSON^TERM event text is set before 
the shell actually terminates. It can do this by calling TERMINATE_PROCESS, one of 
whose parameters is a pointer to this block. 
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FATHER: The father of the shell that just terminated should: 

1) Reav/aJ'ien because it has received the SYS_SON_TERM e-vent via its local 
event channel. 

2) Check the e^/ent text to see what to do. 

Examples 

Following are code segments from both a father shell and a son shell showing the 
start-up and termination of the son. 

These constant and type definitions are used throughout the following examples: 

CONST 

aRestsrt = l; (ftesttrt ne > 

«SBiectAr>?tr>€r = 2; (Seie>:t «notr«r sneii ) 

«StwtAnother s 3; <Stwt the shell naied in the event text ) 

€Off = 4; {Turn off Lisa) 

afteset s 5: <Re4«t the n*:^irie } 

TYPE 

< this is • v.*eiri«rit record which e^liovs ui to Address the packed trrey of crtir ) 

trix = RECORD CASE KOLfrtM OT 

TRUE: (e«^lk: S e.^tDlk); 

FALSE: (zeroth: Tongint: 
first: icfigiht; 

rest: pftiKed 9XJ9^ ti..Rax ertanel of chsr;): 
END; (trix) 

FATHER: This code shows a father shell starting up a son shell and waiting for its 
termdnation. 

PROCEDURE Shell LOOP; 

WAR CSerr: integer; 
proclD: longint; 
fnane: pathname; 
entry: nenestring; 
nextToOo: integer; 
«x n«w: t ex nene; 
€v"ch8n refhcr: integer; 
fw'ch nip»e: pathname; 
MltLlst: t waitlist; 
fwjtr: rjBvantDlk; 

PROCEDURE Stltct^telUSM) fHene: pathnene); 
BEGIN 

MRlTECflaxt 9»n ?•); 

REAOmcfnam): 
END: <Select9«ll} 
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PROOEDCfiS StuffHane(ev Dlk: s e/entDlk; dAM) fntne: pathnane); 
vw Dioct-w- trix: 

1: IKTEGER; 
KGIK 

t>l(Kk.e^lk :s tv Dlk; 

i :« 1; 

*>§«€ :« ••; (null String) 

WIl£ i<>32 00 KGIH 

If fmnefi) « • ' (»p«Pe> TMCH KGIH 

fr»Be[0] :« crir<j-i); <stuff itnotn fitjo) 

CXncStuffHtrte); 
END: (IF) 
frianeti] :e &lock.rest(i]: 

1 :s j ♦ 1; 

END: (WHIlf) 

maf»e[03 :« ohr(32>; <»tuff itrwth field) 
END; (StuffHine) 

BEGIN (srieiiLoop) 

entry := ": 

0piri^Ev»ent_crr><09err . ev_ofi jiar>e , e'^_crf>en_reffKm, ex j^tr»e , recei ve) ; 

SBiectsrieiicmane): 

REPEAT 

mke.ProoesscosEn-.proclD.fnane.tntry.tv chtn refnuB): 

IF (osErr <s 0) THEN BEGIN 

wsdtList.lengtf) :« i; 

wBitList.refrw«i03 :s rv ohtn refnun; 

W8it.EventjCm(osErr,v«LitList7viiicti,«evj>tr)-, 

<c«Je for fither shell Dringirig dovn vx\ sttrts here) 
Ki 1 1 J>r ocess (osErr . prociD) ; 

\f tvj>tr.ewerit.text£0)s&iin.ter« THEN {ciilied ttrnirwiteja'ccess ) 

NextToOo :e"ev ptr.eyifit'textii) 
ELSE 

NextToOo :s aSelectAnothcr; 

END; (PMde the process suooessfully) 

CASE NextToOo OF 

eftestait: (do nothing): 
•SelectAnothei': 9electsnell(fntne>; 

•StwtAnother: StuffNane(e^'j>tr .event text,fnane>; {get nene of Next^^ell out of e^>ent text) 
•Off: ShutOownctOff): <«— turn the nechine off) 

•ieset: sxitoownctReset); {5— reset tne ntcnine) 

OTtCRWISE SelectShell; 
END: {case NextToOo) 

UNTIL HcHFreezesO^ier: 
END: {SneiiUMp) 
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SON: This procedi.o'e mskes the necessary calls for the start-up of © shell. 

PROCEDURE snelilnit; 
VMR CSfelT: IKTEGER; 
Plnfo: ProclnfoRec; 

BEGIN 

info_proc*ss(09err,«y ID, Plnfo); 
If Plnfo.fAtr«r 10 = I <root> T«x begik 
eiocklOinitT (from pp«sudc) 
PMinit; <fror» PMM) 

IF ErjefieDPG T«n 9etJ*ilkey<J5); {sta-icterd mi keycep) 
END: {IF} 
END; {Shelllnit) 

This code shows the shutdown of a shell. If the ShUtDown procedure is declared as 
the ^_Tefminate exception handler, it will properly connmumcate to its father its 
reason for terminating. 

PPOCED.iRE SnutDown (v^y: IMTEGER): 

TYPE 

•JAR 

block: trix: ( the vtri«nt r«corO ) 

NextShell: e nan*:. 

i: IKTEGCR; ~ < for the for loop > 

oarr: INTEGER: < required parareter for the call to terwinete^process > 

8EGIN 

Block. evDlkCll := why; 

IF vhv- 3 tt^tirtTni£Or« then begin 

Hext&*n :« "Shell. next'; 

(copy strirrg without length field) 

TOR I :s 1 TO length(nextshen) W block.rest[i3 :s nextshelUi]: 

FOR i :a length(nextshen) •» i to nex enane DO oiock.restci] := • •; 
END; 

terniri«ite_prccess(OSE!rr , «ii ock . e^t'lk) ; 
END; (ShUtDown) 
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